CLI Reference

Hain’s CLI provides full access to vault, space, file, and sync operations from the command line. Output is designed for both human reading and machine processing.

Global options

These flags work with any command:

--context <id> is still accepted as a deprecated alias for --space <id>.

Vault commands

vault init <path>

Initialize a new vault at the specified path. Sets the vault as the active workspace.

hain vault init ~/my-vault

vault use <path>

Switch to an existing vault.

hain vault use ~/other-vault

vault status

Show current vault status: initialized state, configured path, bootstrap source, and active space.

hain vault status

Space commands

Spaces are isolated workspaces within a vault. Each space lives at a folder you choose on disk, and syncs independently.

hain context … is accepted as a deprecated alias for hain space ….

space list

List all spaces. Shows space ID, name, sync mode, visibility, and which is active.

hain space list

space create <name>

Create a new space. Hain picks a folder for you under the vault’s default space parent, using a slugified version of the name. Use space designate if you want to choose the folder yourself.

hain space create "My Project"

space designate <path> [--multi-writer] [--name <name>]

Bind an existing folder on disk as a space. Hain runs a safety scan over the folder (path blocklist plus sensitive-name walk) before any sync state is written. If the scan surfaces blocking findings, the command stops and asks you to acknowledge them.

hain space designate ~/Documents/team-project --multi-writer --name "Team Project"

Pass --multi-writer for collaborative sync. The default is single-writer (private, no P2P).

space adopt <path>

Re-bind a folder that already contains .context/identity.json into the active vault. Use this after moving a space folder while Hain was stopped, after restoring from backup, or after cloning a .context/-bearing folder onto a new machine.

hain space adopt ~/Documents/restored-project

space preview-designation <path>

Run the designation safety scan against a folder without binding it. Reports any blocking findings, sensitive filenames, large files, and file counts.

hain space preview-designation ~/Documents/team-project

space join <shareKey> [name]

Join an existing space using a 64-character hex share key. Optionally provide a custom name.

hain space join abc123...def "Shared Project"

space switch <id>

Set a space as active for file operations.

hain space switch <space-id>

space rename <id> <name> [--detach-name]

Rename a space. By default, this renames both the folder on disk and the peer-visible display name. Pass --detach-name to update only the display name and leave the folder alone, which is useful when a peer’s local folder name differs from the shared identity.

hain space rename <space-id> "New Name"
hain space rename <space-id> "New Name" --detach-name

space share-key [--space <id>]

Display the share key for a space. Uses the active space if --space is not specified.

hain space share-key

space leave <id>

Leave a space. Files remain on disk in the space’s folder. space delete is accepted as an alias.

hain space leave <space-id>

space forget <id>

Drop a space’s registry binding without touching its folder. Use this when a folder has been deleted or moved off-machine and you want the vault to stop tracking it.

hain space forget <space-id>

space relocate <id> <new-path>

Move a space folder to a new path on the same machine. Updates the registry atomically; sync continues without interruption because the space’s identity is unchanged.

hain space relocate <space-id> ~/Documents/archive/team-project

space subset <sourceId> <files...> --name <name>

Create a new space containing only the specified files from a source space.

hain space subset <source-id> /docs/readme.md /src/index.ts --name "Subset"

File commands

file ls [path]

List directory contents. Defaults to the root /.

hain file ls
hain file ls /src

file mkdir <path>

Create a directory.

hain file mkdir /docs

file touch <path>

Create an empty file.

hain file touch /notes.txt

file cp <src> <dest>

Copy a file or directory within the active space.

hain file cp /readme.md /backup/readme.md

file cpx <srcSpace> <src> <destSpace> <dest>

Copy a file or directory between spaces.

hain file cpx <space-a> /file.txt <space-b> /file.txt

file mv <src> <dest>

Move or rename a file or directory.

hain file mv /old-name.txt /new-name.txt

file rm <path> [--recursive]

Delete a file or directory. Use --recursive for non-empty directories.

hain file rm /temp.txt
hain file rm /old-dir --recursive

file import <external...> [--dest <dir>]

Import files from the local filesystem into the active space.

hain file import ~/Documents/report.pdf --dest /docs
hain file import ~/photos/*.jpg --dest /images

file watch start <path>

Start watching a local directory for changes.

hain file watch start /src

file watch stop <path>

Stop watching a directory.

hain file watch stop /src

file watch list

List all watched directories in the current space.

hain file watch list

Sync commands

sync status [--space <id>]

Show sync status: ready state, peer count, sync status, last update, and any errors.

hain sync status

sync key [--space <id>]

Display the share key. Alias for space share-key.

hain sync key

sync watch [--space <id>]

Watch sync status in real-time. Press Ctrl+C to stop.

hain sync watch

Config commands

config show

Display current application configuration.

hain config show

Update commands

hain update

Upgrade to the latest release on your installed channel. Downloads the platform-specific tarball, verifies its SHA256, smoke-tests the new binary, and atomically swaps ~/.local/share/hain/current to point at the new version.

hain update

hain update --check

Check whether a newer release is available, without installing. Updates state.json.lastCheckAt so the launch-time notice has fresh data.

hain update --check

hain update --version <ver>

Install a specific version. Must be on the same channel as the installed version. A stable install can’t pull a prerelease and vice versa; re-run the curl installer to switch channels.

hain update --version 0.1.0-beta.2

hain update --rollback

Roll back to the previously installed version (still on disk in versions/).

hain update --rollback

hain update --list-installed

List versions retained under versions/, marking current, previous, and the version this process is running from.

hain update --no-prune

Skip the post-install prune step. Older versions stay on disk.

hain update --dry-run

Print what would happen, without downloading or making any filesystem changes.

See the Updating guide for the full mental model.

Command aliases

Exit codes