Shroud CLI

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

Install

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

Or link the bin globally:

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

Quick start

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

Discovery

Every command group is introspectable for automation:

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

Providers

apiKeyRef accepts:

• env:NAME — read from environment variable
• vault:NAME — read from local vault (requires SHROUD_VAULT_PASSPHRASE)
• $SHROUD_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 (SHROUD_ALLOW_OUTSIDE=1 to override).
• Every tool call is appended to $SHROUD_HOME/audit.log (see shroud audit tail).
• Approval flow gates writes, edits, and risky shell commands.

Ignoring paths

When scanning a directory, Shroud reads a .shroudignore 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.

# .shroudignore
fixtures/**
*.min.js

Commands

| Command | Description | | --- | --- | | commands [--tree] | List Shroud 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 Shroud-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 Shroud 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

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

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

License

Apache-2.0