CLI Reference

Reference for Cipher v0.1.0. Run mdstn-cipher help <command> for inline help.

Synopsis

mdstn-cipher [command] [flags]

Zero-config file encryption with managed key lifecycle.

Global flags

These apply to every command.

Flag	Short	Type	Default	Description
`--config`		string	`~/.mdstn/cipher.toml`	Config file path
`--db`		string	`~/.mdstn/cipher.db`	Database path
`--verbose`	`-v`	bool	`false`	Verbose output
`--json`		bool	`false`	Output in JSON format

encrypt

Encrypt a file. Modes: for yourself (default), for a recipient (--for), or with a passphrase.

mdstn-cipher encrypt <file> [flags]

Flag	Short	Type	Default	Description
`--for`		string	—	Encrypt for a recipient email (public key discovered via CKD)
`--passphrase`		string	—	Encrypt with a passphrase (no stored key required)
`--output`	`-o`	string	`<file>.mdstn`	Output file path

mdstn-cipher encrypt secret.pdf
mdstn-cipher encrypt secret.pdf --for alice@team.com
mdstn-cipher encrypt secret.pdf --passphrase

decrypt

Decrypt a .mdstn file. The method is auto-detected from the file header.

mdstn-cipher decrypt <file> [flags]

Flag	Short	Type	Default	Description
`--passphrase`		string	—	Passphrase for decryption
`--output`	`-o`	string	—	Output file path

mdstn-cipher decrypt secret.pdf.mdstn --output secret.pdf

keys

Manage encryption keys.

mdstn-cipher keys <subcommand>

Subcommand	Description
`list`	List all keys
`create`	Create a new key
`delete <key-id>`	Delete a key
`alias <key-id> <alias>`	Set an alias for a key
`export <key-id>`	Export a key
`publish`	Publish your public key to CKD
`unpublish`	Remove your public key from CKD

keys create flags:

Flag	Type	Default	Description
`--type`	string	`x25519`	Key type: `x25519` or `aes256`
`--alias`	string	—	Key alias
`--expires-in`	duration	—	Lifetime, e.g. `30d`, `4w`, `720h`
`--expires-at`	RFC3339	—	Absolute expiry timestamp

keys export flags:

Flag	Short	Type	Default	Description
`--format`		string	`pem`	Export format: `pem` or `raw`
`--output`	`-o`	string	—	Output file path

keys publish / keys unpublish flags:

Flag	Type	Default	Description
`--email`	string	—	Your email address (required)
`--server-url`	string	`$CIPHER_SERVER_URL`	CKD server URL (optional)

mdstn-cipher keys create --alias project-key --expires-in 90d
mdstn-cipher keys export abc123 --format raw --output key.bin
mdstn-cipher keys publish --email alice@team.com

Share keys with team members via a policy/grant model.

mdstn-cipher share <subcommand>

Subcommand	Description
`create <key> --with <email>`	Share a key with another user
`list`	List owned policies and received grants
`revoke <policy-id> <grantee-id>`	Revoke a share grant

mdstn-cipher share create project-key --with bob@team.com

lookup

Look up a public key by email via CKD.

mdstn-cipher lookup <email> [flags]

Flag	Type	Default	Description
`--save`	bool	`false`	Save the result to the local CKD cache
`--json`	bool	`false`	Output as JSON

mdstn-cipher lookup alice@team.com --save

recover

Recover an identity key from a server backup or a BIP39 mnemonic.

mdstn-cipher recover <subcommand>

Subcommand	Description
`from-server`	Recover a key from the server backup (`--key-id <id>`)
`from-mnemonic`	Recover a key from a BIP39 mnemonic (interactive)

mdstn-cipher recover from-server --key-id abc123
mdstn-cipher recover from-mnemonic

backup

Export keys and policies to a backup file.

mdstn-cipher backup [flags]

Flag	Short	Type	Default	Description
`--output`	`-o`	string	`cipher-backup-YYYYMMDD.json`	Output file path

mdstn-cipher backup -o mybackup.json

restore

Import keys and policies from a backup file.

mdstn-cipher restore <backup-file> [flags]

Flag	Type	Default	Description
`--force`	bool	`false`	Overwrite existing keys and policies

mdstn-cipher restore mybackup.json --force

api-key

Manage API keys for programmatic access (keys are formatted ck_live_…).

mdstn-cipher api-key <subcommand>

Subcommand	Description
`create`	Create an API key (`--name <n>`, `--scopes <list>`)
`list`	List all API keys
`revoke <id>`	Revoke an API key

api-key create flags:

Flag	Type	Default	Description
`--name`	string	—	Name for the API key
`--scopes`	string	`admin`	Comma-separated scopes

mdstn-cipher api-key create --name ci-bot --scopes read,encrypt

db

Manage database migrations.

mdstn-cipher db <subcommand>

Subcommand	Description
`up`	Apply all pending migrations
`down`	Roll back the most recent migration
`status`	Show applied and pending migrations
`create <name>`	Create a new blank migration file

mdstn-cipher db status

check-expiry

Scan keys for expiry and record deduplicated notifications. Intended for cron/scripts.

mdstn-cipher check-expiry

mcp

Start the MCP server for AI assistants over stdio JSON-RPC. See MCP Server.

mdstn-cipher mcp

serve

Start the Cipher server (REST API + CKD endpoint + dashboard). Requires PostgreSQL.

mdstn-cipher serve [flags]

Flag	Type	Default	Description
`--port`	int	`8080`	Server port
`--db-url`	string	`$DATABASE_URL`	PostgreSQL connection URL

mdstn-cipher serve --port 8080 --db-url postgres://user:pass@localhost/cipher

version

Show version information.

mdstn-cipher version [--json]

completion

Generate a shell completion script.

mdstn-cipher completion <bash|zsh|fish|powershell>

mdstn-cipher completion zsh > _mdstn-cipher