Sphinx CLI

Local-first secret guard for terminal + AI workflows. Every byte that crosses the model, tool, or session boundary is scanned by Sphinx Secret Guard and plaintext secrets are replaced with $SPHINX_REF(NAME) references resolved from the local encrypted vault.

Install

pnpm install
pnpm -C packages/cli build
node packages/cli/bin/sphinx.mjs --help

Or link the bin globally:

pnpm -C packages/cli link --global
sphinx --help

Quick start

sphinx init                          # create encrypted vault
sphinx scan path/to/file             # find secrets in a file
sphinx scan path/to/dir              # recursively scan a directory
sphinx scan --replace --output clean.txt in.txt  # write sanitized copy
sphinx vault add NAME VALUE          # store a secret locally
sphinx config set provider anthropic # or: openai, openai-compatible, mock
sphinx workspace                     # show workspace context (git, pm, instructions)
sphinx doctor                        # diagnose setup (includes version)
sphinx chat --agent                  # guarded agent loop

Discovery

Every command group is introspectable for automation:

sphinx commands --json               # list top-level commands
sphinx commands --tree --json        # nested commands + subcommands
sphinx <group> commands --json       # subcommands for a group
sphinx tools schema --json           # MCP-compatible tool definitions

Providers

apiKeyRef accepts:

• env:NAME — read from environment variable
• vault:NAME — read from local vault (requires SPHINX_VAULT_PASSPHRASE)
• $SPHINX_REF(NAME) — same as vault:NAME

Built-in providers: mock, anthropic, openai, openai-compatible.

Guard principles

• Secret Guard sanitizes every message before it reaches any model.
• File tools are sandboxed to the current working directory (SPHINX_ALLOW_OUTSIDE=1 to override).
• Every tool call is appended to $SPHINX_HOME/audit.log (see sphinx audit tail).
• Approval flow gates writes, edits, and risky shell commands.

Ignoring paths

When scanning a directory, Sphinx reads a .sphinxignore file at the scan root. Each line is a glob (# comments allowed); matching files are skipped. node_modules and .git are always skipped, and binary files are detected and ignored.

# .sphinxignore
fixtures/**
*.min.js

Commands

| Command | Description | | --- | --- | | commands [--tree] | List Sphinx commands (optionally nested) | | init | Create the encrypted vault | | scan <path> | Scan a file or directory for secrets | | vault add/get/list/rotate/path/rm | Manage local secrets (rotate changes the passphrase, path prints the vault location) | | run <cmd> | Run a command with Sphinx-sanitized output | | config set/get/unset/list/path/reset | Read or update CLI config (path prints config location) | | provider list/set/current/test | Manage AI providers | | approvals list/get/set | Manage approval mode | | doctor | Diagnose Sphinx setup (version + session count) | | session list/latest/show/search/export/diff/rename/clear/delete | Inspect, search & manage sessions (rename, clear --force wipes all) | | audit tail/stats/clear/path | Inspect the audit log (tail --tool/--failed/--since, stats, clear --force) | | tools list/schema/call/show | Inspect & invoke agent tools (schema = MCP, call runs a tool) | | workspace | Show workspace context | | mcp | Run as an MCP server over stdio (secret-guarded tools) | | chat [--agent] [--continue] [--resume <id>] [--model/--provider] | Interactive guarded chat (--model/--provider override config for one run) |

Each group also supports <group> commands [--json] for machine-readable subcommand discovery.

MCP server

sphinx mcp speaks JSON-RPC 2.0 over stdio (initialize, tools/list, tools/call, ping), exposing Sphinx's agent tools to any MCP client. Tool output is secret-sanitized, the cwd sandbox applies (SPHINX_ALLOW_OUTSIDE=1 to override), and destructive shell stays gated. Example client config entry:

{ "mcpServers": { "sphinx": { "command": "sphinx", "args": ["mcp"] } } }

License

Apache-2.0