CLI Reference

Hain’s CLI provides full access to vault, context, 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:

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 context.

hain vault status

Context commands

Contexts are isolated workspaces within a vault. The alias space can be used in place of context in any command.

context list

List all contexts. Shows context ID, name, sync mode, visibility, and which is active.

hain context list

context create <name>

Create a new context.

hain context create "My Project"

context join <shareKey> [name]

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

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

context switch <id>

Set a context as active for file operations.

hain context switch <context-id>

context rename <id> <name>

Rename a context.

hain context rename <context-id> "New Name"

context delete <id>

Remove a context from the vault. Files are preserved on disk.

hain context delete <context-id>

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

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

hain context share-key

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

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

hain context 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 context.

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

file cpx <srcCtx> <src> <destCtx> <dest>

Copy a file or directory between contexts.

hain file cpx <ctx-a> /file.txt <ctx-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 context.

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 context.

hain file watch list

Sync commands

sync status [--context <id>]

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

hain sync status

sync key [--context <id>]

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

hain sync key

sync watch [--context <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

Command aliases

Exit codes