CLI Commands Reference

7 min read

Setup Commands

`ctx-sync init`

Initialize ctx-sync on a new machine. Generates encryption keys and sets up the sync repository.

BASH
ctx-sync init

The remote URL should point to a dedicated private repository you created for ctx-sync (e.g. git@github.com:you/dev-context.git), not one of your project repos. See Getting Started for setup steps.

Options:

Flag	Description
`--restore`	Restore mode — paste an existing private key instead of generating a new one
`--force`	Force key regeneration even if a key already exists (see below)
`--skip-backup`	Skip the key backup prompt (not recommended)
`--remote <url>`	Git remote URL for syncing (SSH or HTTPS)
`--no-interactive`	Skip interactive prompts (use defaults)
`--stdin`	Read private key from stdin (for `--restore`)

🚀

Smart Init

If you already have a key on this machine (e.g. you ran `init` before), running `ctx-sync init` again will **reuse your existing key** and only update the remote configuration. This is useful when you need to add or change a remote URL without accidentally regenerating your encryption key. To force a new key pair, pass `--force`.

`ctx-sync init --restore`

Set up ctx-sync on a new machine using an existing private key.

BASH
ctx-sync init --restore

You will be prompted to paste your private key and provide the Git remote URL.

Project Management

`ctx-sync track`

Track the current project. Auto-detects Git state, .env files, Docker services, and prompts for mental context.

BASH
ctx-sync track

Options:

Flag	Description
`--yes`	Skip confirmation prompts (auto-accept defaults)
`--no-interactive`	Non-interactive mode for CI/scripts

`ctx-sync list`

List all tracked projects.

BASH
ctx-sync list

`ctx-sync status`

Show the sync status — pending changes, last sync time, and remote state.

BASH
ctx-sync status

`ctx-sync restore `

Restore a project's full context on the current machine.

BASH
ctx-sync restore my-app

By default, restore automatically pulls the latest state from the remote before decrypting, so you always get the most current context — even if you synced from another machine moments ago.

This displays your mental context, decrypts environment variables, and shows all commands (Docker, services) for explicit approval before execution.

Options:

Flag	Description
`--no-pull`	Skip the automatic pull and restore from local state only
`--path <dir>`	Use a different local directory for the project (for cross-machine restores where the project lives at a different path)

🚀

Cross-Machine Path Resolution

When you restore on a different machine, the stored project path may not exist. Use `--path` to tell ctx-sync where the project lives on this machine:

BASH
ctx-sync restore my-app --path ~/code/my-app

If the stored path doesn't exist and --path is not provided, ctx-sync falls back to the current working directory with a warning.

🔒

Command Approval Required

Commands are always shown for review before execution. There is no flag to skip command confirmation. This prevents remote code execution from compromised repos.

Environment Variables

`ctx-sync env import `

Import environment variables from a .env file. All values are encrypted by default.

BASH
ctx-sync env import .env

Options:

Flag	Description
`--stdin`	Read from stdin instead of a file
`--allow-plain`	Allow safe-listed keys to be stored unencrypted

`ctx-sync env add `

Add a single environment variable. Value is entered via hidden interactive prompt — never passed as a CLI argument.

BASH
ctx-sync env add STRIPE_KEY

Options:

Flag	Description
`--stdin`	Read value from stdin pipe
`--from-fd N`	Read value from file descriptor N

⚠️

Never Pass Secrets as Arguments

Values are never accepted as CLI arguments to prevent exposure in shell history and process lists. Use interactive prompt, stdin, or file descriptor instead.

`ctx-sync env scan`

Scan the current shell environment and select variables to track.

BASH
ctx-sync env scan my-app

`ctx-sync env list `

List all tracked environment variables for a project. Values are hidden by default.

BASH
ctx-sync env list my-app

Options:

Flag	Description
`--show-values`	Show decrypted values (use with caution)

Syncing

`ctx-sync sync`

Sync context with the remote — pushes local changes and pulls remote updates.

BASH
ctx-sync sync

`ctx-sync push`

Push local context to the remote.

BASH
ctx-sync push

`ctx-sync pull`

Pull remote context to the local machine.

BASH
ctx-sync pull

Mental Context

`ctx-sync note `

Update mental context — current task, blockers, next steps, breadcrumbs, and links.

BASH
ctx-sync note my-app

🚀

Beat the 23-Minute Problem

Use `ctx-sync note` at the end of each session to capture what you were doing, where you left off, and what you planned to do next. Your future self will thank you.

`ctx-sync show `

Display the full context for a project — Git state, environment variables, Docker services, and mental context.

BASH
ctx-sync show my-app

Docker

`ctx-sync docker start `

Start tracked Docker services for a project. Commands are shown for confirmation before execution.

BASH
ctx-sync docker start my-app

Options:

Flag	Description
`--path <dir>`	Use a different local directory (for cross-machine restores where the project lives at a different path)
`--no-interactive`	Show commands but skip execution

`ctx-sync docker stop `

Stop tracked Docker services.

BASH
ctx-sync docker stop my-app

Options:

Flag	Description
`--path <dir>`	Use a different local directory (for cross-machine restores where the project lives at a different path)

🚀

Cross-Machine Docker Support

When you run Docker commands on a different machine, the stored Docker Compose path may not exist. Use `--path` to tell ctx-sync where the project (and its `docker-compose.yml`) lives on this machine:

BASH
ctx-sync docker start my-app --path ~/code/my-app
ctx-sync docker stop my-app --path ~/code/my-app

If the stored path doesn't exist and --path is not provided, ctx-sync falls back to the current working directory with a warning.

`ctx-sync docker status`

Show the status of tracked Docker services.

BASH
ctx-sync docker status

Key Management

`ctx-sync key show`

Display your public key. The private key is never shown.

BASH
ctx-sync key show

`ctx-sync key rotate`

Rotate your encryption key. Generates a new key pair and re-encrypts all state files.

BASH
ctx-sync key rotate

What it does:

Generates a new key pair
Re-encrypts all state files with the new key
Rewrites Git history to remove old encrypted blobs
Force-pushes to remote

⚠️

Coordinate Key Rotation

After rotation, all other machines must run `ctx-sync key update`. Failure to do so will prevent decryption on those machines.

`ctx-sync key verify`

Verify key file permissions and integrity.

BASH
ctx-sync key verify

`ctx-sync key update`

Update the private key on this machine after a key rotation on another machine.

BASH
ctx-sync key update

Team Management

`ctx-sync team add`

Add a team member as a recipient for encrypted state.

BASH
ctx-sync team add --name "Alice" --key age1alice...

`ctx-sync team remove `

Remove a team member and re-encrypt all shared state.

BASH
ctx-sync team remove alice

`ctx-sync team list`

List all team members and their public keys.

BASH
ctx-sync team list

`ctx-sync team revoke `

Immediately revoke a key and re-encrypt all shared secrets.

BASH
ctx-sync team revoke age1bob...

Configuration

`ctx-sync config safe-list`

View the current safe-list of environment variable keys that may be stored unencrypted.

BASH
ctx-sync config safe-list

`ctx-sync config safe-list add `

Add a key to the safe-list.

BASH
ctx-sync config safe-list add MY_SAFE_VAR

`ctx-sync config safe-list remove `

Remove a key from the safe-list.

BASH
ctx-sync config safe-list remove MY_SAFE_VAR

Security

`ctx-sync audit`

Run a comprehensive security audit of your ctx-sync setup.

BASH
ctx-sync audit

Checks:

Key file permissions (must be 600)
Config directory permissions (must be 700)
Git remote transport security (SSH or HTTPS only)
Git history for plaintext leaks
Repository size
All state files are encrypted

✅

Run Audits Regularly

Make `ctx-sync audit` part of your routine. It catches permission drift, insecure remotes, and accidentally committed plaintext files.