Auto-Generated CLI Documentation - Summary¶
✅ Setup Complete!¶
Your project now has automatic CLI documentation generation configured.
What Was Done¶
1. Dependencies Added¶
✅ Added mkdocs-click>=0.8.0 to:
- pyproject.toml (docs extra)
- pyproject.toml (all extra)
2. MkDocs Configuration Updated¶
✅ Added mkdocs_click to markdown_extensions in mkdocs.yml
Note: It's a Markdown extension, not a plugin!
3. Documentation Created¶
Three new example pages were created:
docs/reference/cli-auto.md- Complete working example
- Shows all mkdocs-click features
-
Multiple display patterns
- Comprehensive integration guide
- Best practices
-
Troubleshooting tips
- Quick start guide
- Common patterns
-
5-minute setup
- Example of hybrid documentation
- Manual content + auto-generated
- Real-world integration pattern
How to Use¶
Quick Test¶
# Start docs server
mkdocs serve
# Open browser to http://127.0.0.1:8000
# Navigate to "Examples" > "CLI Auto Quickstart"
Add to Any Page¶
Just add this to your markdown:
# secretzero sync { #secretzero-sync data-toc-label='secretzero sync' }
Generate and synchronize secrets to targets.
When the global ``--non-interactive`` flag is set, interactive prompts are
automatically disabled (equivalent to ``--no-prompt``).
This command generates secret values according to your Secretfile
configuration and stores them in the specified targets (local files,
cloud providers, etc.).
By default, syncs all secrets. Use --secret to sync specific secrets only.
Variable files (.szvar) can be used to override variables defined in the
Secretfile. Multiple variable files can be specified, and they are merged
in order with later files taking precedence.
Examples:
# Sync all secrets
secretzero sync
# Sync with variable file override
secretzero sync --var-file dev.szvar
# Sync with multiple variable files
secretzero sync --var-file base.szvar --var-file dev.szvar
# Sync only specific secrets
secretzero sync --secret db_password --secret api_key
# Short form
secretzero sync -s db_password -s api_key
# Re-push to one target when several exist and others are already synced
secretzero sync -s api_key --force-target local/file/.env.production
# Preview plan before applying
secretzero sync --plan
# Machine-readable plan output
secretzero sync --plan --format json
# Opt out of automatic pre-sync refresh
secretzero sync --no-refresh
**Usage:**
```text
secretzero sync [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--lockfile, -l |
path | Path to lockfile | .gitsecrets.lock |
--var-file, -v |
path | Path to .szvar variable file(s) to merge (can be specified multiple times) | Sentinel.UNSET |
--environment, -e |
text | Named environment profile from Secretfile.environments.profiles | None |
--dry-run |
boolean | Show what would be done without making changes | False |
--plan |
boolean | Show detailed execution plan (created/updated/unchanged/skipped) without applying | False |
--show-input |
boolean | Show secret input as plain text when prompting (default: masked) | False |
--no-prompt |
boolean | Disable interactive prompts (fail if values are missing) - useful for CI/CD | False |
--secret, -s |
text | Sync only specific secrets by name (can be specified multiple times) | Sentinel.UNSET |
--format |
choice (text | json) |
Output format (text or json) | text |
--clean |
boolean | Remove lockfile entries that have no corresponding secret in the Secretfile | False |
--refresh / --no-refresh |
boolean | Refresh lockfile target validity right before sync (default: enabled; use --no-refresh to opt out) | True |
--force-target |
text | Re-push the current secret value to these target IDs only (repeatable). Target IDs match the lockfile (e.g. local/file/.env, github/github_secret/…). Requires exactly one --secret. Use when multiple targets exist and at least one is already synced. | Sentinel.UNSET |
--help, -h |
boolean | Show this message and exit. | False |
## Common Usage Patterns
### Full CLI Reference (All Commands)
```markdown
### secretzero { #secretzero data-toc-label='secretzero' }
SecretZero: Secrets orchestration, lifecycle, and bootstrap engine.
SecretZero helps automate the creation, seeding, and lifecycle management
of project secrets through a declarative, schema-driven workflow.
**Usage:**
```text
secretzero [OPTIONS] COMMAND [ARGS]...
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--version |
boolean | Show the version and exit. | False |
--non-interactive, -n |
boolean | Disable all interactive prompts; error when human input would be required. | False |
--help, -h |
boolean | Show this message and exit. | False |
secretzero agent¶
Agent-specific commands for autonomous secret management.
These commands are designed for use by AI agents and automation tools that need to manage secrets with minimal human intervention. They provide structured output and guided instructions for secrets that require manual acquisition.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help, -h |
boolean | Show this message and exit. | False |
secretzero agent sync¶
Agent-aware secret synchronisation with guided instructions.
The --interactive flag is rejected when --non-interactive is set.
Automatically syncs secrets that can be generated without external input and provides structured step-by-step instructions for secrets that require manual acquisition (sign-ups, OAuth flows, admin approvals, etc.).
Examples:
# Run agent sync and view instructions for pending secrets
secretzero agent sync
# Output machine-readable JSON for further processing
secretzero agent sync --json
# Preview what would happen without making changes
secretzero agent sync --dry-run
# Interactively supply values for pending secrets
secretzero agent sync --interactive
# Secure local web form for manual values (never echoed to the agent)
secretzero agent sync --web
# Sync with variable file override
secretzero agent sync --var-file dev.szvar
# Opt out of automatic pre-sync refresh
secretzero agent sync --no-refresh
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--lockfile, -l |
path | Path to lockfile | .gitsecrets.lock |
--var-file, -v |
path | Path to .szvar variable file(s) to merge (can be specified multiple times) | Sentinel.UNSET |
--environment, -e |
text | Named environment profile from Secretfile.environments.profiles | None |
--dry-run |
boolean | Preview changes without applying them | False |
--json |
boolean | Output results as JSON (machine-readable) | False |
--interactive |
boolean | Prompt for manual secrets interactively (CLI prompts; not used with --web) | False |
--web |
boolean | Collect manual secret values via a temporary localhost web form (Vector 2) | False |
--web-host |
text | DEPRECATED: agent web mode always binds to 127.0.0.1 for safety | 127.0.0.1 |
--verbose, -V |
boolean | Verbose logging for agent sync | False |
--refresh / --no-refresh |
boolean | Refresh lockfile target validity right before sync (default: enabled; use --no-refresh to opt out) | True |
--help, -h |
boolean | Show this message and exit. | False |
secretzero audit¶
View API audit logs.
Displays audit log entries recorded by the SecretZero API. Logs are written to a file when the API server is running.
Examples:
# Show recent audit logs
secretzero audit
# Filter by action
secretzero audit --action sync
# Filter by resource
secretzero audit --resource secrets
# Show in JSON format
secretzero audit --format json
# Show last 100 entries
secretzero audit --limit 100
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--limit, -n |
integer | Maximum number of log entries to return | 50 |
--offset |
integer | Number of entries to skip | 0 |
--action, -a |
text | Filter logs by action name | None |
--resource, -r |
text | Filter logs by resource name | None |
--log-file |
path | Path to audit log file | .secretzero_audit.log |
--format |
choice (text | json) |
Output format (text or json) | text |
--help, -h |
boolean | Show this message and exit. | False |
secretzero auth¶
Authenticate with providers interactively.
Use auth login to start an interactive OAuth device flow for a
supported provider, and auth status to inspect the current token.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help, -h |
boolean | Show this message and exit. | False |
secretzero auth login¶
Log in to a provider using the OAuth device flow.
Starts the OAuth 2.0 Device Authorization Grant. You will be shown a one-time code and a URL to visit in your browser. After authorizing, the CLI receives an access token.
Examples: secretzero auth login --provider github --client-id Iv1.abc123 secretzero auth login -p github --client-id Iv1.abc123 --scopes repo,workflow secretzero auth login -p github --client-id Iv1.abc123 --save-to .env
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--provider, -p |
text | Provider to authenticate with (e.g. github) | Sentinel.UNSET |
--client-id |
text | OAuth App client ID registered with the provider | Sentinel.UNSET |
--scopes, -s |
text | Comma-separated OAuth scopes (default: provider-specific) | None |
--no-browser |
boolean | Don't open the browser automatically | False |
--save-to |
path | Write the token to a file (e.g. .env). Format: KEY=VALUE | None |
--env-var |
text | Environment variable name used when writing to --save-to (default: provider-specific) | None |
--help, -h |
boolean | Show this message and exit. | False |
secretzero auth status¶
Show information about the current authentication token.
Inspects the token found in the provider's expected environment variable
(e.g. GITHUB_TOKEN) and displays user, scopes, and token type.
Examples: secretzero auth status --provider github secretzero auth status -p github --format json
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--provider, -p |
text | Provider to check token status for (e.g. github) | Sentinel.UNSET |
--format |
choice (text | json) |
Output format | text |
--help, -h |
boolean | Show this message and exit. | False |
secretzero config¶
Show or update application config (defaults ← config.yml ← Secretfile config).
Resolves config from: built-in defaults, then ~/.config/secretzero/config.yml,
then the optional config block in the given Secretfile.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile (for show: merge project config; for update: target file) | Secretfile.yml |
--format |
choice (text | json | yaml) |
Output format (show command) | text |
--help, -h |
boolean | Show this message and exit. | False |
secretzero config show¶
Show effective application config (default command).
Resolves centralized config from: built-in defaults, then
~/.config/secretzero/config.yml if present, then the optional config
block in the given Secretfile.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile (used to merge project config block if present) | Secretfile.yml |
--format |
choice (text | json | yaml) |
Output format | text |
--help, -h |
boolean | Show this message and exit. | False |
secretzero config update¶
Set a config key idempotently (e.g. llm.default_provider, llm.providers.ollama.model).
Updates either the project Secretfile config block or the user config file.
Key path is dot-separated (e.g. llm.model, llm.providers.ollama.base_url).
Value is written as-is; numbers and booleans are coerced when possible.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Secretfile path to update (default: Secretfile.yml). Use --user for user config. | None |
--user |
boolean | Update user config (~/.config/secretzero/config.yml) instead of Secretfile | False |
--dry-run |
boolean | Print what would be written without changing files | False |
--help, -h |
boolean | Show this message and exit. | False |
secretzero create¶
Create a new Secretfile from a template.
This command generates a starter Secretfile.yml with example configurations for different provider types.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--template-type |
choice (basic | aws | azure | vault | kubernetes) |
Template type to use for initialization | basic |
--output, -o |
path | Output file path | Secretfile.yml |
--help, -h |
boolean | Show this message and exit. | False |
secretzero detect¶
Scan a directory for potential secrets and suggest Secretfile definitions.
Looks for common secret patterns in files: .env files, config files, and environment variable references. Outputs a suggested Secretfile fragment that can be added to your Secretfile.yml.
Examples:
# Scan current directory
secretzero detect
# Scan specific directory
secretzero detect ./src
# Output suggested config as JSON
secretzero detect --format json
# Save suggestion to file
secretzero detect -o suggested.yml
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--format |
choice (text | json) |
Output format (text or json) | text |
--output, -o |
path | Write suggested Secretfile fragment to file instead of stdout | None |
--help, -h |
boolean | Show this message and exit. | False |
secretzero discover¶
AI-powered secret discovery.
Scans a project directory for secrets, credentials, and sensitive
configuration values. Generates a Secretfile.detect.yml with
recommended secret definitions that you can review and use as a
starting point for your Secretfile.yml.
Examples: # Basic scan of current directory secretzero discover
# Use OpenAI for deeper analysis secretzero discover --provider openai
# Privacy-first local-only scan secretzero discover --local-only
# Dry-run to preview without writing secretzero discover --dry-run
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--path, -p |
directory | Project root directory to scan | . |
--output, -o |
path | Output path for Secretfile.detect.yml (default: |
None |
--dry-run |
boolean | Analyse without writing output files | False |
--provider |
choice (ollama | openai | anthropic | azure_openai) |
LLM provider to use for AI-enhanced analysis | None |
--model |
text | LLM model name override | None |
--local-only |
boolean | Restrict to local LLM providers only (e.g. Ollama) | False |
--no-llm |
boolean | Disable LLM analysis; use pattern matching only | False |
--config, -c |
path | Path to secretzero.yml configuration file | None |
--format, -f |
choice (text | json | yaml) |
Output summary format | text |
--threshold |
float | Confidence threshold (0.0–1.0) for including secrets (default from config) | None |
--verbose, -v |
boolean | Show detailed LLM prompts and responses (text/json output only) | False |
--help, -h |
boolean | Show this message and exit. | False |
secretzero drift¶
Detect drift between lockfile and actual targets.
This command checks if secrets have been modified outside of SecretZero's control.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--lockfile, -l |
path | Path to lockfile | .gitsecrets.lock |
--format |
choice (text | json) |
Output format (text or json) | text |
--help, -h |
boolean | Show this message and exit. | False |
secretzero format¶
Validate and reformat a Secretfile.yml without losing comments.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile.yml to validate and format | Secretfile.yml |
--dry-run |
boolean | Validate and print formatted YAML to stdout without modifying the file | False |
--add-missing |
boolean | Also add missing default values inside the config block (creating it if missing) | False |
--help, -h |
boolean | Show this message and exit. | False |
secretzero get¶
Retrieve a secret value through provider bundle methods.
This command is sandbox-protected:
- SZ_SANDBOX=true blocks retrieval.
- SZ_ALLOW_GET_IN_SANDBOX=true explicitly overrides the block.
By default, output is metadata-only. Pass --reveal to include plaintext
when the provider API returns a revealable value.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--lockfile, -l |
path | Path to lockfile | .gitsecrets.lock |
--provider |
text | Configured provider alias from Secretfile | Sentinel.UNSET |
--secret-id |
text | Provider secret identifier/path | Sentinel.UNSET |
--method |
text | Provider retrieval method (default: retrieve_secret, fallback: get_secret) | Sentinel.UNSET |
--arg |
text | Method argument in KEY=VALUE form (repeatable). VALUE may be JSON. | Sentinel.UNSET |
--reveal |
boolean | Include secret value in output when provider supports plaintext retrieval. | False |
--policy-check / --no-policy-check |
boolean | Validate policy violations before retrieval. | True |
--format |
choice (text | json) |
Output format (text or json) | text |
--help, -h |
boolean | Show this message and exit. | False |
secretzero graph¶
Generate visual graph of Secretfile relationships.
This command creates visual representations of your secret flows, showing generators, secrets, and their target destinations.
Graph Types:
- flow: Simple flowchart showing generator → secret → target relationships
- detailed: Detailed view with configuration parameters
- architecture: High-level system architecture view
- destination: Destination-centric view grouped by target destinations and keys
Output Formats:
- mermaid: Mermaid diagram markdown (can be rendered in GitHub, docs, etc.)
- terminal: Text-based summary for console viewing
- json: Machine-readable nodes and edges
Examples:
# Generate simple flow diagram
secretzero graph
# Generate detailed diagram with configs
secretzero graph --type detailed
# Generate architecture overview
secretzero graph --type architecture
# Generate destination-centric overview
secretzero graph --type destination
# Save to file
secretzero graph --output secretflow.md
# Terminal-friendly summary
secretzero graph --format terminal
# Machine-readable JSON graph
secretzero graph --format json
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--type, -t |
choice (flow | detailed | architecture | destination) |
Type of graph to generate | flow |
--format, -o |
choice (mermaid | terminal | json) |
Output format (mermaid, terminal, or json) | mermaid |
--output |
path | Output file path (prints to console if not specified) | None |
--help, -h |
boolean | Show this message and exit. | False |
secretzero import¶
Import pre-seeded values from targets into the lockfile (read-only on targets).
Refreshes stale lockfile target IDs, then reads each secret from configured targets and
updates lockfile hashes when values are consistent across targets. Use --check for a
drift-only report (add --fail-on-drift for CI-style gating).
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--lockfile, -l |
path | Path to lockfile | .gitsecrets.lock |
--var-file, -v |
path | Path to .szvar variable file(s) to merge (repeatable) | Sentinel.UNSET |
--environment, -e |
text | Named environment profile from Secretfile.environments.profiles | None |
--dry-run |
boolean | Show what would be imported without updating the lockfile | False |
--check |
boolean | Report drift between lockfile and live targets only (no import) | False |
--fail-on-drift |
boolean | With --check, exit with a non-zero status when drift is detected | False |
--secret, -s |
text | Import only these secrets (repeatable) | Sentinel.UNSET |
--format |
choice (text | json) |
Output format (text or json) | text |
--help, -h |
boolean | Show this message and exit. | False |
secretzero init¶
Initialize project by checking and installing provider dependencies.
This command reads your Secretfile, identifies configured providers, and checks if the required libraries are installed. It can optionally install missing dependencies automatically.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--install |
boolean | Automatically install missing dependencies | False |
--dry-run |
boolean | Show what would be installed without installing | False |
--help, -h |
boolean | Show this message and exit. | False |
secretzero list¶
List secrets, providers, targets, or variables from a Secretfile.
Named list_group so the built-in list remains available in this module
(a function named list would shadow it and break list(...) calls below).
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help, -h |
boolean | Show this message and exit. | False |
secretzero list providers¶
List all providers configured in the Secretfile.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--format |
choice (text | json) |
Output format (text or json) | text |
--help, -h |
boolean | Show this message and exit. | False |
secretzero list secrets¶
List all secrets defined in the Secretfile.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--format |
choice (text | json) |
Output format (text or json) | text |
--filter |
text | Filter secrets by name substring | None |
--help, -h |
boolean | Show this message and exit. | False |
secretzero list targets¶
List all target destinations across all secrets in the Secretfile.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--format |
choice (text | json) |
Output format (text or json) | text |
--help, -h |
boolean | Show this message and exit. | False |
secretzero list variables¶
List all variables defined in the Secretfile.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--format |
choice (text | json) |
Output format (text or json) | text |
--filter |
text | Filter variables by name substring | None |
--help, -h |
boolean | Show this message and exit. | False |
secretzero policy¶
Check secrets against policy rules.
This command validates secrets against rotation, compliance, and access control policies defined in the Secretfile.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--lockfile, -l |
path | Path to lockfile | .gitsecrets.lock |
--fail-on-warning |
boolean | Exit with error code on policy warnings | False |
--format |
choice (text | json) |
Output format (text or json) | text |
--help, -h |
boolean | Show this message and exit. | False |
secretzero providers¶
Manage and introspect providers.
Providers are external systems (Vault, AWS, Azure, etc.) that store or help manage secrets. These commands let you discover available providers and their capabilities.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help, -h |
boolean | Show this message and exit. | False |
secretzero providers capabilities¶
Show capabilities of a specific provider.
Lists all operations (methods) that a provider supports.
Example: secretzero providers capabilities vault
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help, -h |
boolean | Show this message and exit. | False |
secretzero providers list¶
List all registered providers.
Shows all provider types available in SecretZero.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help, -h |
boolean | Show this message and exit. | False |
secretzero providers methods¶
List methods for a provider, optionally filtered by type.
Examples: secretzero providers methods vault secretzero providers methods vault --type generate secretzero providers methods aws -t retrieve
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--type, -t |
choice (generate | retrieve | store | rotate | delete | all) |
Filter by capability type | all |
--help, -h |
boolean | Show this message and exit. | False |
secretzero providers schema¶
Show schema/signature for a specific provider method.
Displays the parameters and return type for a method.
Example: secretzero providers schema vault generate_password
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--json |
boolean | Output as JSON instead of formatted text | False |
--help, -h |
boolean | Show this message and exit. | False |
secretzero providers token-info¶
Show authentication token permissions and scopes.
Queries the provider's auth layer for token details such as user
identity, granted scopes, and common operations. Any provider whose
auth class implements get_token_info is supported.
PROVIDER_TYPE defaults to "github" when omitted.
Examples:
# Check GITHUB_TOKEN environment variable
secretzero providers token-info
# Check a specific token
secretzero providers token-info github --token ghp_xxxxx
# Use a different provider (if it supports token introspection)
secretzero providers token-info vault --token s.xxxxxxx
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--token, -t |
text | Token to check (falls back to provider-specific env var, e.g. GITHUB_TOKEN) | Sentinel.UNSET |
--help, -h |
boolean | Show this message and exit. | False |
secretzero render¶
Render the final Secretfile configuration with variables interpolated.
This command displays or saves the complete Secretfile configuration after merging variable files and applying variable interpolation. This is useful for debugging variable issues or understanding the final configuration.
Variable files (.szvar) are merged in order with later files taking precedence.
Examples:
# Render to stdout
secretzero render
# Render with variable file
secretzero render --var-file dev.szvar
# Render with multiple variable files
secretzero render --var-file base.szvar --var-file dev.szvar
# Render to file in JSON format
secretzero render --var-file dev.szvar --format json --output rendered.json
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--var-file, -v |
path | Path to .szvar variable file(s) to merge (can be specified multiple times) | Sentinel.UNSET |
--format |
choice (yaml | json) |
Output format (yaml or json) | yaml |
--output, -o |
path | Write output to file instead of stdout | Sentinel.UNSET |
--help, -h |
boolean | Show this message and exit. | False |
secretzero rotate¶
Rotate secrets based on rotation policies.
This command checks which secrets need rotation and regenerates them. Respects rotation_period settings and one_time flags.
Limit to specific secrets with --secret / -s (repeatable) or a single
optional SECRET_NAME positional argument — not both.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--lockfile, -l |
path | Path to lockfile | .gitsecrets.lock |
--force |
boolean | Force rotation even if not due | False |
--dry-run |
boolean | Show what would be rotated without making changes | False |
--show-input |
boolean | Show secret input as plain text when prompting (default: masked) | False |
--format |
choice (text | json) |
Output format (text or json) | text |
--secret, -s |
text | Rotate only this secret by name (repeat for multiple secrets) | Sentinel.UNSET |
--help, -h |
boolean | Show this message and exit. | False |
secretzero scaffold-bundle¶
Scaffold a new SecretZero provider bundle package.
NAME is the provider identifier (e.g. "mycloud"). The command creates a pip-installable package with all the boilerplate needed for a provider, optional targets and generators, a bundle manifest, pyproject.toml, and starter tests.
Examples: secretzero scaffold-bundle mycloud secretzero scaffold-bundle mycloud --with-target mycloud_secret --with-generator mycloud_token secretzero scaffold-bundle mycloud -o ~/projects
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--output-dir, -o |
path | Parent directory for the generated package (default: current directory) | . |
--with-target |
text | Target kind to include (can be repeated, e.g. --with-target my_secret) | Sentinel.UNSET |
--with-generator |
text | Generator kind to include (can be repeated, e.g. --with-generator my_token) | Sentinel.UNSET |
--description |
text | Short description for the provider | None |
--help, -h |
boolean | Show this message and exit. | False |
secretzero schema¶
Schema utilities for Secretfile.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help, -h |
boolean | Show this message and exit. | False |
secretzero schema export¶
Export JSON Schema for Secretfile.yml.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--output, -o |
path | Output file path or '-' for stdout | - |
--help, -h |
boolean | Show this message and exit. | False |
secretzero secret-types¶
List supported secret types and generators.
Shows all available secret generator types that can be used in your Secretfile configuration, along with their supported parameters.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--type, -t |
text | Show details for a specific secret type | Sentinel.UNSET |
--verbose, -v |
boolean | Show detailed information | False |
--help, -h |
boolean | Show this message and exit. | False |
secretzero show¶
Show information about secrets.
If no secret name is provided, displays a list of all secrets in the manifest file. If a secret name is provided, displays detailed metadata about that specific secret, including its configuration, generation status, and target storage locations.
Use --detailed to show complete configuration and sub-fields.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--lockfile, -l |
path | Path to lockfile | .gitsecrets.lock |
--detailed, -d |
boolean | Show detailed configuration and sub-fields | False |
--help, -h |
boolean | Show this message and exit. | False |
secretzero status¶
Show synchronization status of secrets and targets.
This command displays which secrets have been generated and synced to their configured targets, along with timestamps and rotation information.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--lockfile, -l |
path | Path to lockfile | .gitsecrets.lock |
--verbose, -v |
boolean | Show detailed information including target hashes | False |
--format |
choice (text | json) |
Output format (text or json) | text |
--help, -h |
boolean | Show this message and exit. | False |
secretzero sync¶
Generate and synchronize secrets to targets.
When the global --non-interactive flag is set, interactive prompts are
automatically disabled (equivalent to --no-prompt).
This command generates secret values according to your Secretfile configuration and stores them in the specified targets (local files, cloud providers, etc.).
By default, syncs all secrets. Use --secret to sync specific secrets only.
Variable files (.szvar) can be used to override variables defined in the Secretfile. Multiple variable files can be specified, and they are merged in order with later files taking precedence.
Examples:
# Sync all secrets
secretzero sync
# Sync with variable file override
secretzero sync --var-file dev.szvar
# Sync with multiple variable files
secretzero sync --var-file base.szvar --var-file dev.szvar
# Sync only specific secrets
secretzero sync --secret db_password --secret api_key
# Short form
secretzero sync -s db_password -s api_key
# Re-push to one target when several exist and others are already synced
secretzero sync -s api_key --force-target local/file/.env.production
# Preview plan before applying
secretzero sync --plan
# Machine-readable plan output
secretzero sync --plan --format json
# Opt out of automatic pre-sync refresh
secretzero sync --no-refresh
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--lockfile, -l |
path | Path to lockfile | .gitsecrets.lock |
--var-file, -v |
path | Path to .szvar variable file(s) to merge (can be specified multiple times) | Sentinel.UNSET |
--environment, -e |
text | Named environment profile from Secretfile.environments.profiles | None |
--dry-run |
boolean | Show what would be done without making changes | False |
--plan |
boolean | Show detailed execution plan (created/updated/unchanged/skipped) without applying | False |
--show-input |
boolean | Show secret input as plain text when prompting (default: masked) | False |
--no-prompt |
boolean | Disable interactive prompts (fail if values are missing) - useful for CI/CD | False |
--secret, -s |
text | Sync only specific secrets by name (can be specified multiple times) | Sentinel.UNSET |
--format |
choice (text | json) |
Output format (text or json) | text |
--clean |
boolean | Remove lockfile entries that have no corresponding secret in the Secretfile | False |
--refresh / --no-refresh |
boolean | Refresh lockfile target validity right before sync (default: enabled; use --no-refresh to opt out) | True |
--force-target |
text | Re-push the current secret value to these target IDs only (repeatable). Target IDs match the lockfile (e.g. local/file/.env, github/github_secret/…). Requires exactly one --secret. Use when multiple targets exist and at least one is already synced. | Sentinel.UNSET |
--help, -h |
boolean | Show this message and exit. | False |
secretzero terraform¶
Generate Terraform manifests from a Secretfile.
This command translates your Secretfile configuration into Terraform
resources, using bundle-provided Terraform provider metadata where
available. Generated configuration can be emitted as HCL (.tf)
or Terraform JSON (.tf.json).
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--var-file, -v |
path | Path to .szvar variable file(s) (can be specified multiple times) | Sentinel.UNSET |
--output-dir, -o |
path | Directory to write generated Terraform files | terraform-out |
--format |
choice (hcl | json) |
Terraform output format (hcl or json) | hcl |
--include-static-secrets / --no-include-static-secrets |
boolean | Include default values for static-secret Terraform variables (may embed secrets in code). | False |
--dry-run |
boolean | Show a summary of what would be generated without writing files | False |
--help, -h |
boolean | Show this message and exit. | False |
secretzero test¶
Test provider connectivity and authentication.
This command validates that all configured providers can be authenticated and accessed successfully. Use --include-profiles to also test each defined authentication profile for providers that support them. Use --verbose to see detailed error information when tests fail.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--include-profiles |
boolean | Test each defined authentication profile for providers | False |
--verbose, -v |
boolean | Show detailed error information including stack traces | False |
--help, -h |
boolean | Show this message and exit. | False |
secretzero validate¶
Validate Secretfile configuration.
This command checks the syntax and structure of your Secretfile.yml, ensuring all required fields are present and properly formatted.
Variable files (.szvar) can be specified for validation to ensure the final merged configuration is valid.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--var-file, -v |
path | Path to .szvar variable file(s) to validate with (can be specified multiple times) | Sentinel.UNSET |
--format |
choice (text | json) |
Output format (text or json) | text |
--help, -h |
boolean | Show this message and exit. | False |
secretzero validate-bundle¶
Validate a SecretZero provider bundle.
PATH can be a directory containing a Python package or a Python file
that exports a BUNDLE_MANIFEST attribute.
Checks performed:
- BUNDLE_MANIFEST is a valid BundleManifest
- All declared dotted class paths can be imported
- Provider class inherits from BaseProvider
- Generator classes inherit from BaseGenerator
- Target classes inherit from BaseTarget
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--output-format |
choice (text | json) |
Output format | text |
--help, -h |
boolean | Show this message and exit. | False |
secretzero web¶
Serve an HTTPS-capable web UI to inspect the manifest, sync, and update secrets.
Binds to all interfaces by default. Share the printed URL and bootstrap token out of band. For trusted transport use --tls-self-signed, your own --tls-cert / --tls-key, an SSH tunnel, or a reverse proxy with a real certificate.
Use Shut down in the UI to stop the server; the CLI also saves the lockfile when the session ends.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--lockfile, -l |
path | Path to lockfile | .gitsecrets.lock |
--var-file, -v |
path | Path to .szvar variable file(s) to merge (can be specified multiple times) | Sentinel.UNSET |
--environment, -e |
text | Named environment profile from Secretfile.environments.profiles | None |
--dry-run |
boolean | Preview only; does not open the network web UI | False |
--host |
text | Address to bind (use 127.0.0.1 for local-only) | 0.0.0.0 |
--port |
integer | TCP port (default: random in agent web_port_min–web_port_max from Secretfile) | None |
--token |
text | Bootstrap access token (default: generate randomly) | None |
--token-file |
path | Read bootstrap token from file (whitespace trimmed); overrides --token | None |
--tls-cert |
path | PEM TLS certificate for HTTPS | None |
--tls-key |
path | PEM TLS private key for HTTPS | None |
--tls-self-signed |
boolean | Generate a short-lived self-signed certificate (requires cryptography) | False |
--tls-san |
text | Extra Subject Alternative Name (hostname or IP); repeat for multiple (with --tls-self-signed) | () |
--timeout |
float | Seconds to wait before timing out if the UI is not shut down | 3600.0 |
--debug |
boolean | Show a structured sync debug log at the bottom of the dashboard (no secret values). | False |
--help, -h |
boolean | Show this message and exit. | False |
### Single Command
```markdown
# secretzero sync { #secretzero-sync data-toc-label='secretzero sync' }
Generate and synchronize secrets to targets.
When the global ``--non-interactive`` flag is set, interactive prompts are
automatically disabled (equivalent to ``--no-prompt``).
This command generates secret values according to your Secretfile
configuration and stores them in the specified targets (local files,
cloud providers, etc.).
By default, syncs all secrets. Use --secret to sync specific secrets only.
Variable files (.szvar) can be used to override variables defined in the
Secretfile. Multiple variable files can be specified, and they are merged
in order with later files taking precedence.
Examples:
# Sync all secrets
secretzero sync
# Sync with variable file override
secretzero sync --var-file dev.szvar
# Sync with multiple variable files
secretzero sync --var-file base.szvar --var-file dev.szvar
# Sync only specific secrets
secretzero sync --secret db_password --secret api_key
# Short form
secretzero sync -s db_password -s api_key
# Re-push to one target when several exist and others are already synced
secretzero sync -s api_key --force-target local/file/.env.production
# Preview plan before applying
secretzero sync --plan
# Machine-readable plan output
secretzero sync --plan --format json
# Opt out of automatic pre-sync refresh
secretzero sync --no-refresh
**Usage:**
```text
secretzero sync [OPTIONS]
Options:
-f, --file PATH Path to Secretfile
-l, --lockfile PATH Path to lockfile
-v, --var-file PATH Path to .szvar variable file(s) to merge (can be
specified multiple times)
-e, --environment TEXT Named environment profile from
Secretfile.environments.profiles
--dry-run Show what would be done without making changes
--plan Show detailed execution plan
(created/updated/unchanged/skipped) without
applying
--show-input Show secret input as plain text when prompting
(default: masked)
--no-prompt Disable interactive prompts (fail if values are
missing) - useful for CI/CD
-s, --secret TEXT Sync only specific secrets by name (can be
specified multiple times)
--format [text|json] Output format (text or json)
--clean Remove lockfile entries that have no corresponding
secret in the Secretfile
--refresh / --no-refresh Refresh lockfile target validity right before sync
(default: enabled; use --no-refresh to opt out)
--force-target TEXT Re-push the current secret value to these target
IDs only (repeatable). Target IDs match the
lockfile (e.g. local/file/.env,
github/github_secret/…). Requires exactly one
--secret. Use when multiple targets exist and at
least one is already synced.
-h, --help Show this message and exit.
### Hybrid Page (Recommended)
```markdown
# secretzero sync
Your manual introduction, examples, and context...
## Command Reference
# secretzero sync { #secretzero-sync data-toc-label='secretzero sync' }
Generate and synchronize secrets to targets.
When the global ``--non-interactive`` flag is set, interactive prompts are
automatically disabled (equivalent to ``--no-prompt``).
This command generates secret values according to your Secretfile
configuration and stores them in the specified targets (local files,
cloud providers, etc.).
By default, syncs all secrets. Use --secret to sync specific secrets only.
Variable files (.szvar) can be used to override variables defined in the
Secretfile. Multiple variable files can be specified, and they are merged
in order with later files taking precedence.
Examples:
# Sync all secrets
secretzero sync
# Sync with variable file override
secretzero sync --var-file dev.szvar
# Sync with multiple variable files
secretzero sync --var-file base.szvar --var-file dev.szvar
# Sync only specific secrets
secretzero sync --secret db_password --secret api_key
# Short form
secretzero sync -s db_password -s api_key
# Re-push to one target when several exist and others are already synced
secretzero sync -s api_key --force-target local/file/.env.production
# Preview plan before applying
secretzero sync --plan
# Machine-readable plan output
secretzero sync --plan --format json
# Opt out of automatic pre-sync refresh
secretzero sync --no-refresh
**Usage:**
```text
secretzero sync [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--lockfile, -l |
path | Path to lockfile | .gitsecrets.lock |
--var-file, -v |
path | Path to .szvar variable file(s) to merge (can be specified multiple times) | Sentinel.UNSET |
--environment, -e |
text | Named environment profile from Secretfile.environments.profiles | None |
--dry-run |
boolean | Show what would be done without making changes | False |
--plan |
boolean | Show detailed execution plan (created/updated/unchanged/skipped) without applying | False |
--show-input |
boolean | Show secret input as plain text when prompting (default: masked) | False |
--no-prompt |
boolean | Disable interactive prompts (fail if values are missing) - useful for CI/CD | False |
--secret, -s |
text | Sync only specific secrets by name (can be specified multiple times) | Sentinel.UNSET |
--format |
choice (text | json) |
Output format (text or json) | text |
--clean |
boolean | Remove lockfile entries that have no corresponding secret in the Secretfile | False |
--refresh / --no-refresh |
boolean | Refresh lockfile target validity right before sync (default: enabled; use --no-refresh to opt out) | True |
--force-target |
text | Re-push the current secret value to these target IDs only (repeatable). Target IDs match the lockfile (e.g. local/file/.env, github/github_secret/…). Requires exactly one --secret. Use when multiple targets exist and at least one is already synced. | Sentinel.UNSET |
--help, -h |
boolean | Show this message and exit. | False |
More Examples¶
Additional manual content...
## Update Existing Pages
To integrate into your existing CLI documentation:
### Option 1: Add Auto-Generated Section
Add this to any existing command page (e.g., `docs/user-guide/cli/sync.md`):
```markdown
## Command Reference (Auto-Generated)
# secretzero sync { #secretzero-sync data-toc-label='secretzero sync' }
Generate and synchronize secrets to targets.
When the global ``--non-interactive`` flag is set, interactive prompts are
automatically disabled (equivalent to ``--no-prompt``).
This command generates secret values according to your Secretfile
configuration and stores them in the specified targets (local files,
cloud providers, etc.).
By default, syncs all secrets. Use --secret to sync specific secrets only.
Variable files (.szvar) can be used to override variables defined in the
Secretfile. Multiple variable files can be specified, and they are merged
in order with later files taking precedence.
Examples:
# Sync all secrets
secretzero sync
# Sync with variable file override
secretzero sync --var-file dev.szvar
# Sync with multiple variable files
secretzero sync --var-file base.szvar --var-file dev.szvar
# Sync only specific secrets
secretzero sync --secret db_password --secret api_key
# Short form
secretzero sync -s db_password -s api_key
# Re-push to one target when several exist and others are already synced
secretzero sync -s api_key --force-target local/file/.env.production
# Preview plan before applying
secretzero sync --plan
# Machine-readable plan output
secretzero sync --plan --format json
# Opt out of automatic pre-sync refresh
secretzero sync --no-refresh
**Usage:**
```text
secretzero sync [OPTIONS]
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--lockfile, -l |
path | Path to lockfile | .gitsecrets.lock |
--var-file, -v |
path | Path to .szvar variable file(s) to merge (can be specified multiple times) | Sentinel.UNSET |
--environment, -e |
text | Named environment profile from Secretfile.environments.profiles | None |
--dry-run |
boolean | Show what would be done without making changes | False |
--plan |
boolean | Show detailed execution plan (created/updated/unchanged/skipped) without applying | False |
--show-input |
boolean | Show secret input as plain text when prompting (default: masked) | False |
--no-prompt |
boolean | Disable interactive prompts (fail if values are missing) - useful for CI/CD | False |
--secret, -s |
text | Sync only specific secrets by name (can be specified multiple times) | Sentinel.UNSET |
--format |
choice (text | json) |
Output format (text or json) | text |
--clean |
boolean | Remove lockfile entries that have no corresponding secret in the Secretfile | False |
--refresh / --no-refresh |
boolean | Refresh lockfile target validity right before sync (default: enabled; use --no-refresh to opt out) | True |
--force-target |
text | Re-push the current secret value to these target IDs only (repeatable). Target IDs match the lockfile (e.g. local/file/.env, github/github_secret/…). Requires exactly one --secret. Use when multiple targets exist and at least one is already synced. | Sentinel.UNSET |
--help, -h |
boolean | Show this message and exit. | False |
This section is automatically generated from the source code.
### Option 2: Create Separate Auto Pages
Create `docs/reference/cli-commands-auto.md`:
```markdown
# CLI Commands (Auto-Generated)
Complete reference for all commands:
### secretzero { #secretzero data-toc-label='secretzero' }
SecretZero: Secrets orchestration, lifecycle, and bootstrap engine.
SecretZero helps automate the creation, seeding, and lifecycle management
of project secrets through a declarative, schema-driven workflow.
**Usage:**
```text
secretzero [OPTIONS] COMMAND [ARGS]...
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--version |
boolean | Show the version and exit. | False |
--non-interactive, -n |
boolean | Disable all interactive prompts; error when human input would be required. | False |
--help, -h |
boolean | Show this message and exit. | False |
secretzero agent¶
Agent-specific commands for autonomous secret management.
These commands are designed for use by AI agents and automation tools that need to manage secrets with minimal human intervention. They provide structured output and guided instructions for secrets that require manual acquisition.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help, -h |
boolean | Show this message and exit. | False |
secretzero agent sync¶
Agent-aware secret synchronisation with guided instructions.
The --interactive flag is rejected when --non-interactive is set.
Automatically syncs secrets that can be generated without external input and provides structured step-by-step instructions for secrets that require manual acquisition (sign-ups, OAuth flows, admin approvals, etc.).
Examples:
# Run agent sync and view instructions for pending secrets
secretzero agent sync
# Output machine-readable JSON for further processing
secretzero agent sync --json
# Preview what would happen without making changes
secretzero agent sync --dry-run
# Interactively supply values for pending secrets
secretzero agent sync --interactive
# Secure local web form for manual values (never echoed to the agent)
secretzero agent sync --web
# Sync with variable file override
secretzero agent sync --var-file dev.szvar
# Opt out of automatic pre-sync refresh
secretzero agent sync --no-refresh
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--lockfile, -l |
path | Path to lockfile | .gitsecrets.lock |
--var-file, -v |
path | Path to .szvar variable file(s) to merge (can be specified multiple times) | Sentinel.UNSET |
--environment, -e |
text | Named environment profile from Secretfile.environments.profiles | None |
--dry-run |
boolean | Preview changes without applying them | False |
--json |
boolean | Output results as JSON (machine-readable) | False |
--interactive |
boolean | Prompt for manual secrets interactively (CLI prompts; not used with --web) | False |
--web |
boolean | Collect manual secret values via a temporary localhost web form (Vector 2) | False |
--web-host |
text | DEPRECATED: agent web mode always binds to 127.0.0.1 for safety | 127.0.0.1 |
--verbose, -V |
boolean | Verbose logging for agent sync | False |
--refresh / --no-refresh |
boolean | Refresh lockfile target validity right before sync (default: enabled; use --no-refresh to opt out) | True |
--help, -h |
boolean | Show this message and exit. | False |
secretzero audit¶
View API audit logs.
Displays audit log entries recorded by the SecretZero API. Logs are written to a file when the API server is running.
Examples:
# Show recent audit logs
secretzero audit
# Filter by action
secretzero audit --action sync
# Filter by resource
secretzero audit --resource secrets
# Show in JSON format
secretzero audit --format json
# Show last 100 entries
secretzero audit --limit 100
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--limit, -n |
integer | Maximum number of log entries to return | 50 |
--offset |
integer | Number of entries to skip | 0 |
--action, -a |
text | Filter logs by action name | None |
--resource, -r |
text | Filter logs by resource name | None |
--log-file |
path | Path to audit log file | .secretzero_audit.log |
--format |
choice (text | json) |
Output format (text or json) | text |
--help, -h |
boolean | Show this message and exit. | False |
secretzero auth¶
Authenticate with providers interactively.
Use auth login to start an interactive OAuth device flow for a
supported provider, and auth status to inspect the current token.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help, -h |
boolean | Show this message and exit. | False |
secretzero auth login¶
Log in to a provider using the OAuth device flow.
Starts the OAuth 2.0 Device Authorization Grant. You will be shown a one-time code and a URL to visit in your browser. After authorizing, the CLI receives an access token.
Examples: secretzero auth login --provider github --client-id Iv1.abc123 secretzero auth login -p github --client-id Iv1.abc123 --scopes repo,workflow secretzero auth login -p github --client-id Iv1.abc123 --save-to .env
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--provider, -p |
text | Provider to authenticate with (e.g. github) | Sentinel.UNSET |
--client-id |
text | OAuth App client ID registered with the provider | Sentinel.UNSET |
--scopes, -s |
text | Comma-separated OAuth scopes (default: provider-specific) | None |
--no-browser |
boolean | Don't open the browser automatically | False |
--save-to |
path | Write the token to a file (e.g. .env). Format: KEY=VALUE | None |
--env-var |
text | Environment variable name used when writing to --save-to (default: provider-specific) | None |
--help, -h |
boolean | Show this message and exit. | False |
secretzero auth status¶
Show information about the current authentication token.
Inspects the token found in the provider's expected environment variable
(e.g. GITHUB_TOKEN) and displays user, scopes, and token type.
Examples: secretzero auth status --provider github secretzero auth status -p github --format json
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--provider, -p |
text | Provider to check token status for (e.g. github) | Sentinel.UNSET |
--format |
choice (text | json) |
Output format | text |
--help, -h |
boolean | Show this message and exit. | False |
secretzero config¶
Show or update application config (defaults ← config.yml ← Secretfile config).
Resolves config from: built-in defaults, then ~/.config/secretzero/config.yml,
then the optional config block in the given Secretfile.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile (for show: merge project config; for update: target file) | Secretfile.yml |
--format |
choice (text | json | yaml) |
Output format (show command) | text |
--help, -h |
boolean | Show this message and exit. | False |
secretzero config show¶
Show effective application config (default command).
Resolves centralized config from: built-in defaults, then
~/.config/secretzero/config.yml if present, then the optional config
block in the given Secretfile.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile (used to merge project config block if present) | Secretfile.yml |
--format |
choice (text | json | yaml) |
Output format | text |
--help, -h |
boolean | Show this message and exit. | False |
secretzero config update¶
Set a config key idempotently (e.g. llm.default_provider, llm.providers.ollama.model).
Updates either the project Secretfile config block or the user config file.
Key path is dot-separated (e.g. llm.model, llm.providers.ollama.base_url).
Value is written as-is; numbers and booleans are coerced when possible.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Secretfile path to update (default: Secretfile.yml). Use --user for user config. | None |
--user |
boolean | Update user config (~/.config/secretzero/config.yml) instead of Secretfile | False |
--dry-run |
boolean | Print what would be written without changing files | False |
--help, -h |
boolean | Show this message and exit. | False |
secretzero create¶
Create a new Secretfile from a template.
This command generates a starter Secretfile.yml with example configurations for different provider types.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--template-type |
choice (basic | aws | azure | vault | kubernetes) |
Template type to use for initialization | basic |
--output, -o |
path | Output file path | Secretfile.yml |
--help, -h |
boolean | Show this message and exit. | False |
secretzero detect¶
Scan a directory for potential secrets and suggest Secretfile definitions.
Looks for common secret patterns in files: .env files, config files, and environment variable references. Outputs a suggested Secretfile fragment that can be added to your Secretfile.yml.
Examples:
# Scan current directory
secretzero detect
# Scan specific directory
secretzero detect ./src
# Output suggested config as JSON
secretzero detect --format json
# Save suggestion to file
secretzero detect -o suggested.yml
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--format |
choice (text | json) |
Output format (text or json) | text |
--output, -o |
path | Write suggested Secretfile fragment to file instead of stdout | None |
--help, -h |
boolean | Show this message and exit. | False |
secretzero discover¶
AI-powered secret discovery.
Scans a project directory for secrets, credentials, and sensitive
configuration values. Generates a Secretfile.detect.yml with
recommended secret definitions that you can review and use as a
starting point for your Secretfile.yml.
Examples: # Basic scan of current directory secretzero discover
# Use OpenAI for deeper analysis secretzero discover --provider openai
# Privacy-first local-only scan secretzero discover --local-only
# Dry-run to preview without writing secretzero discover --dry-run
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--path, -p |
directory | Project root directory to scan | . |
--output, -o |
path | Output path for Secretfile.detect.yml (default: |
None |
--dry-run |
boolean | Analyse without writing output files | False |
--provider |
choice (ollama | openai | anthropic | azure_openai) |
LLM provider to use for AI-enhanced analysis | None |
--model |
text | LLM model name override | None |
--local-only |
boolean | Restrict to local LLM providers only (e.g. Ollama) | False |
--no-llm |
boolean | Disable LLM analysis; use pattern matching only | False |
--config, -c |
path | Path to secretzero.yml configuration file | None |
--format, -f |
choice (text | json | yaml) |
Output summary format | text |
--threshold |
float | Confidence threshold (0.0–1.0) for including secrets (default from config) | None |
--verbose, -v |
boolean | Show detailed LLM prompts and responses (text/json output only) | False |
--help, -h |
boolean | Show this message and exit. | False |
secretzero drift¶
Detect drift between lockfile and actual targets.
This command checks if secrets have been modified outside of SecretZero's control.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--lockfile, -l |
path | Path to lockfile | .gitsecrets.lock |
--format |
choice (text | json) |
Output format (text or json) | text |
--help, -h |
boolean | Show this message and exit. | False |
secretzero format¶
Validate and reformat a Secretfile.yml without losing comments.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile.yml to validate and format | Secretfile.yml |
--dry-run |
boolean | Validate and print formatted YAML to stdout without modifying the file | False |
--add-missing |
boolean | Also add missing default values inside the config block (creating it if missing) | False |
--help, -h |
boolean | Show this message and exit. | False |
secretzero get¶
Retrieve a secret value through provider bundle methods.
This command is sandbox-protected:
- SZ_SANDBOX=true blocks retrieval.
- SZ_ALLOW_GET_IN_SANDBOX=true explicitly overrides the block.
By default, output is metadata-only. Pass --reveal to include plaintext
when the provider API returns a revealable value.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--lockfile, -l |
path | Path to lockfile | .gitsecrets.lock |
--provider |
text | Configured provider alias from Secretfile | Sentinel.UNSET |
--secret-id |
text | Provider secret identifier/path | Sentinel.UNSET |
--method |
text | Provider retrieval method (default: retrieve_secret, fallback: get_secret) | Sentinel.UNSET |
--arg |
text | Method argument in KEY=VALUE form (repeatable). VALUE may be JSON. | Sentinel.UNSET |
--reveal |
boolean | Include secret value in output when provider supports plaintext retrieval. | False |
--policy-check / --no-policy-check |
boolean | Validate policy violations before retrieval. | True |
--format |
choice (text | json) |
Output format (text or json) | text |
--help, -h |
boolean | Show this message and exit. | False |
secretzero graph¶
Generate visual graph of Secretfile relationships.
This command creates visual representations of your secret flows, showing generators, secrets, and their target destinations.
Graph Types:
- flow: Simple flowchart showing generator → secret → target relationships
- detailed: Detailed view with configuration parameters
- architecture: High-level system architecture view
- destination: Destination-centric view grouped by target destinations and keys
Output Formats:
- mermaid: Mermaid diagram markdown (can be rendered in GitHub, docs, etc.)
- terminal: Text-based summary for console viewing
- json: Machine-readable nodes and edges
Examples:
# Generate simple flow diagram
secretzero graph
# Generate detailed diagram with configs
secretzero graph --type detailed
# Generate architecture overview
secretzero graph --type architecture
# Generate destination-centric overview
secretzero graph --type destination
# Save to file
secretzero graph --output secretflow.md
# Terminal-friendly summary
secretzero graph --format terminal
# Machine-readable JSON graph
secretzero graph --format json
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--type, -t |
choice (flow | detailed | architecture | destination) |
Type of graph to generate | flow |
--format, -o |
choice (mermaid | terminal | json) |
Output format (mermaid, terminal, or json) | mermaid |
--output |
path | Output file path (prints to console if not specified) | None |
--help, -h |
boolean | Show this message and exit. | False |
secretzero import¶
Import pre-seeded values from targets into the lockfile (read-only on targets).
Refreshes stale lockfile target IDs, then reads each secret from configured targets and
updates lockfile hashes when values are consistent across targets. Use --check for a
drift-only report (add --fail-on-drift for CI-style gating).
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--lockfile, -l |
path | Path to lockfile | .gitsecrets.lock |
--var-file, -v |
path | Path to .szvar variable file(s) to merge (repeatable) | Sentinel.UNSET |
--environment, -e |
text | Named environment profile from Secretfile.environments.profiles | None |
--dry-run |
boolean | Show what would be imported without updating the lockfile | False |
--check |
boolean | Report drift between lockfile and live targets only (no import) | False |
--fail-on-drift |
boolean | With --check, exit with a non-zero status when drift is detected | False |
--secret, -s |
text | Import only these secrets (repeatable) | Sentinel.UNSET |
--format |
choice (text | json) |
Output format (text or json) | text |
--help, -h |
boolean | Show this message and exit. | False |
secretzero init¶
Initialize project by checking and installing provider dependencies.
This command reads your Secretfile, identifies configured providers, and checks if the required libraries are installed. It can optionally install missing dependencies automatically.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--install |
boolean | Automatically install missing dependencies | False |
--dry-run |
boolean | Show what would be installed without installing | False |
--help, -h |
boolean | Show this message and exit. | False |
secretzero list¶
List secrets, providers, targets, or variables from a Secretfile.
Named list_group so the built-in list remains available in this module
(a function named list would shadow it and break list(...) calls below).
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help, -h |
boolean | Show this message and exit. | False |
secretzero list providers¶
List all providers configured in the Secretfile.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--format |
choice (text | json) |
Output format (text or json) | text |
--help, -h |
boolean | Show this message and exit. | False |
secretzero list secrets¶
List all secrets defined in the Secretfile.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--format |
choice (text | json) |
Output format (text or json) | text |
--filter |
text | Filter secrets by name substring | None |
--help, -h |
boolean | Show this message and exit. | False |
secretzero list targets¶
List all target destinations across all secrets in the Secretfile.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--format |
choice (text | json) |
Output format (text or json) | text |
--help, -h |
boolean | Show this message and exit. | False |
secretzero list variables¶
List all variables defined in the Secretfile.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--format |
choice (text | json) |
Output format (text or json) | text |
--filter |
text | Filter variables by name substring | None |
--help, -h |
boolean | Show this message and exit. | False |
secretzero policy¶
Check secrets against policy rules.
This command validates secrets against rotation, compliance, and access control policies defined in the Secretfile.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--lockfile, -l |
path | Path to lockfile | .gitsecrets.lock |
--fail-on-warning |
boolean | Exit with error code on policy warnings | False |
--format |
choice (text | json) |
Output format (text or json) | text |
--help, -h |
boolean | Show this message and exit. | False |
secretzero providers¶
Manage and introspect providers.
Providers are external systems (Vault, AWS, Azure, etc.) that store or help manage secrets. These commands let you discover available providers and their capabilities.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help, -h |
boolean | Show this message and exit. | False |
secretzero providers capabilities¶
Show capabilities of a specific provider.
Lists all operations (methods) that a provider supports.
Example: secretzero providers capabilities vault
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help, -h |
boolean | Show this message and exit. | False |
secretzero providers list¶
List all registered providers.
Shows all provider types available in SecretZero.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help, -h |
boolean | Show this message and exit. | False |
secretzero providers methods¶
List methods for a provider, optionally filtered by type.
Examples: secretzero providers methods vault secretzero providers methods vault --type generate secretzero providers methods aws -t retrieve
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--type, -t |
choice (generate | retrieve | store | rotate | delete | all) |
Filter by capability type | all |
--help, -h |
boolean | Show this message and exit. | False |
secretzero providers schema¶
Show schema/signature for a specific provider method.
Displays the parameters and return type for a method.
Example: secretzero providers schema vault generate_password
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--json |
boolean | Output as JSON instead of formatted text | False |
--help, -h |
boolean | Show this message and exit. | False |
secretzero providers token-info¶
Show authentication token permissions and scopes.
Queries the provider's auth layer for token details such as user
identity, granted scopes, and common operations. Any provider whose
auth class implements get_token_info is supported.
PROVIDER_TYPE defaults to "github" when omitted.
Examples:
# Check GITHUB_TOKEN environment variable
secretzero providers token-info
# Check a specific token
secretzero providers token-info github --token ghp_xxxxx
# Use a different provider (if it supports token introspection)
secretzero providers token-info vault --token s.xxxxxxx
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--token, -t |
text | Token to check (falls back to provider-specific env var, e.g. GITHUB_TOKEN) | Sentinel.UNSET |
--help, -h |
boolean | Show this message and exit. | False |
secretzero render¶
Render the final Secretfile configuration with variables interpolated.
This command displays or saves the complete Secretfile configuration after merging variable files and applying variable interpolation. This is useful for debugging variable issues or understanding the final configuration.
Variable files (.szvar) are merged in order with later files taking precedence.
Examples:
# Render to stdout
secretzero render
# Render with variable file
secretzero render --var-file dev.szvar
# Render with multiple variable files
secretzero render --var-file base.szvar --var-file dev.szvar
# Render to file in JSON format
secretzero render --var-file dev.szvar --format json --output rendered.json
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--var-file, -v |
path | Path to .szvar variable file(s) to merge (can be specified multiple times) | Sentinel.UNSET |
--format |
choice (yaml | json) |
Output format (yaml or json) | yaml |
--output, -o |
path | Write output to file instead of stdout | Sentinel.UNSET |
--help, -h |
boolean | Show this message and exit. | False |
secretzero rotate¶
Rotate secrets based on rotation policies.
This command checks which secrets need rotation and regenerates them. Respects rotation_period settings and one_time flags.
Limit to specific secrets with --secret / -s (repeatable) or a single
optional SECRET_NAME positional argument — not both.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--lockfile, -l |
path | Path to lockfile | .gitsecrets.lock |
--force |
boolean | Force rotation even if not due | False |
--dry-run |
boolean | Show what would be rotated without making changes | False |
--show-input |
boolean | Show secret input as plain text when prompting (default: masked) | False |
--format |
choice (text | json) |
Output format (text or json) | text |
--secret, -s |
text | Rotate only this secret by name (repeat for multiple secrets) | Sentinel.UNSET |
--help, -h |
boolean | Show this message and exit. | False |
secretzero scaffold-bundle¶
Scaffold a new SecretZero provider bundle package.
NAME is the provider identifier (e.g. "mycloud"). The command creates a pip-installable package with all the boilerplate needed for a provider, optional targets and generators, a bundle manifest, pyproject.toml, and starter tests.
Examples: secretzero scaffold-bundle mycloud secretzero scaffold-bundle mycloud --with-target mycloud_secret --with-generator mycloud_token secretzero scaffold-bundle mycloud -o ~/projects
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--output-dir, -o |
path | Parent directory for the generated package (default: current directory) | . |
--with-target |
text | Target kind to include (can be repeated, e.g. --with-target my_secret) | Sentinel.UNSET |
--with-generator |
text | Generator kind to include (can be repeated, e.g. --with-generator my_token) | Sentinel.UNSET |
--description |
text | Short description for the provider | None |
--help, -h |
boolean | Show this message and exit. | False |
secretzero schema¶
Schema utilities for Secretfile.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help, -h |
boolean | Show this message and exit. | False |
secretzero schema export¶
Export JSON Schema for Secretfile.yml.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--output, -o |
path | Output file path or '-' for stdout | - |
--help, -h |
boolean | Show this message and exit. | False |
secretzero secret-types¶
List supported secret types and generators.
Shows all available secret generator types that can be used in your Secretfile configuration, along with their supported parameters.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--type, -t |
text | Show details for a specific secret type | Sentinel.UNSET |
--verbose, -v |
boolean | Show detailed information | False |
--help, -h |
boolean | Show this message and exit. | False |
secretzero show¶
Show information about secrets.
If no secret name is provided, displays a list of all secrets in the manifest file. If a secret name is provided, displays detailed metadata about that specific secret, including its configuration, generation status, and target storage locations.
Use --detailed to show complete configuration and sub-fields.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--lockfile, -l |
path | Path to lockfile | .gitsecrets.lock |
--detailed, -d |
boolean | Show detailed configuration and sub-fields | False |
--help, -h |
boolean | Show this message and exit. | False |
secretzero status¶
Show synchronization status of secrets and targets.
This command displays which secrets have been generated and synced to their configured targets, along with timestamps and rotation information.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--lockfile, -l |
path | Path to lockfile | .gitsecrets.lock |
--verbose, -v |
boolean | Show detailed information including target hashes | False |
--format |
choice (text | json) |
Output format (text or json) | text |
--help, -h |
boolean | Show this message and exit. | False |
secretzero sync¶
Generate and synchronize secrets to targets.
When the global --non-interactive flag is set, interactive prompts are
automatically disabled (equivalent to --no-prompt).
This command generates secret values according to your Secretfile configuration and stores them in the specified targets (local files, cloud providers, etc.).
By default, syncs all secrets. Use --secret to sync specific secrets only.
Variable files (.szvar) can be used to override variables defined in the Secretfile. Multiple variable files can be specified, and they are merged in order with later files taking precedence.
Examples:
# Sync all secrets
secretzero sync
# Sync with variable file override
secretzero sync --var-file dev.szvar
# Sync with multiple variable files
secretzero sync --var-file base.szvar --var-file dev.szvar
# Sync only specific secrets
secretzero sync --secret db_password --secret api_key
# Short form
secretzero sync -s db_password -s api_key
# Re-push to one target when several exist and others are already synced
secretzero sync -s api_key --force-target local/file/.env.production
# Preview plan before applying
secretzero sync --plan
# Machine-readable plan output
secretzero sync --plan --format json
# Opt out of automatic pre-sync refresh
secretzero sync --no-refresh
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--lockfile, -l |
path | Path to lockfile | .gitsecrets.lock |
--var-file, -v |
path | Path to .szvar variable file(s) to merge (can be specified multiple times) | Sentinel.UNSET |
--environment, -e |
text | Named environment profile from Secretfile.environments.profiles | None |
--dry-run |
boolean | Show what would be done without making changes | False |
--plan |
boolean | Show detailed execution plan (created/updated/unchanged/skipped) without applying | False |
--show-input |
boolean | Show secret input as plain text when prompting (default: masked) | False |
--no-prompt |
boolean | Disable interactive prompts (fail if values are missing) - useful for CI/CD | False |
--secret, -s |
text | Sync only specific secrets by name (can be specified multiple times) | Sentinel.UNSET |
--format |
choice (text | json) |
Output format (text or json) | text |
--clean |
boolean | Remove lockfile entries that have no corresponding secret in the Secretfile | False |
--refresh / --no-refresh |
boolean | Refresh lockfile target validity right before sync (default: enabled; use --no-refresh to opt out) | True |
--force-target |
text | Re-push the current secret value to these target IDs only (repeatable). Target IDs match the lockfile (e.g. local/file/.env, github/github_secret/…). Requires exactly one --secret. Use when multiple targets exist and at least one is already synced. | Sentinel.UNSET |
--help, -h |
boolean | Show this message and exit. | False |
secretzero terraform¶
Generate Terraform manifests from a Secretfile.
This command translates your Secretfile configuration into Terraform
resources, using bundle-provided Terraform provider metadata where
available. Generated configuration can be emitted as HCL (.tf)
or Terraform JSON (.tf.json).
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--var-file, -v |
path | Path to .szvar variable file(s) (can be specified multiple times) | Sentinel.UNSET |
--output-dir, -o |
path | Directory to write generated Terraform files | terraform-out |
--format |
choice (hcl | json) |
Terraform output format (hcl or json) | hcl |
--include-static-secrets / --no-include-static-secrets |
boolean | Include default values for static-secret Terraform variables (may embed secrets in code). | False |
--dry-run |
boolean | Show a summary of what would be generated without writing files | False |
--help, -h |
boolean | Show this message and exit. | False |
secretzero test¶
Test provider connectivity and authentication.
This command validates that all configured providers can be authenticated and accessed successfully. Use --include-profiles to also test each defined authentication profile for providers that support them. Use --verbose to see detailed error information when tests fail.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--include-profiles |
boolean | Test each defined authentication profile for providers | False |
--verbose, -v |
boolean | Show detailed error information including stack traces | False |
--help, -h |
boolean | Show this message and exit. | False |
secretzero validate¶
Validate Secretfile configuration.
This command checks the syntax and structure of your Secretfile.yml, ensuring all required fields are present and properly formatted.
Variable files (.szvar) can be specified for validation to ensure the final merged configuration is valid.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--var-file, -v |
path | Path to .szvar variable file(s) to validate with (can be specified multiple times) | Sentinel.UNSET |
--format |
choice (text | json) |
Output format (text or json) | text |
--help, -h |
boolean | Show this message and exit. | False |
secretzero validate-bundle¶
Validate a SecretZero provider bundle.
PATH can be a directory containing a Python package or a Python file
that exports a BUNDLE_MANIFEST attribute.
Checks performed:
- BUNDLE_MANIFEST is a valid BundleManifest
- All declared dotted class paths can be imported
- Provider class inherits from BaseProvider
- Generator classes inherit from BaseGenerator
- Target classes inherit from BaseTarget
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--output-format |
choice (text | json) |
Output format | text |
--help, -h |
boolean | Show this message and exit. | False |
secretzero web¶
Serve an HTTPS-capable web UI to inspect the manifest, sync, and update secrets.
Binds to all interfaces by default. Share the printed URL and bootstrap token out of band. For trusted transport use --tls-self-signed, your own --tls-cert / --tls-key, an SSH tunnel, or a reverse proxy with a real certificate.
Use Shut down in the UI to stop the server; the CLI also saves the lockfile when the session ends.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--file, -f |
path | Path to Secretfile | Secretfile.yml |
--lockfile, -l |
path | Path to lockfile | .gitsecrets.lock |
--var-file, -v |
path | Path to .szvar variable file(s) to merge (can be specified multiple times) | Sentinel.UNSET |
--environment, -e |
text | Named environment profile from Secretfile.environments.profiles | None |
--dry-run |
boolean | Preview only; does not open the network web UI | False |
--host |
text | Address to bind (use 127.0.0.1 for local-only) | 0.0.0.0 |
--port |
integer | TCP port (default: random in agent web_port_min–web_port_max from Secretfile) | None |
--token |
text | Bootstrap access token (default: generate randomly) | None |
--token-file |
path | Read bootstrap token from file (whitespace trimmed); overrides --token | None |
--tls-cert |
path | PEM TLS certificate for HTTPS | None |
--tls-key |
path | PEM TLS private key for HTTPS | None |
--tls-self-signed |
boolean | Generate a short-lived self-signed certificate (requires cryptography) | False |
--tls-san |
text | Extra Subject Alternative Name (hostname or IP); repeat for multiple (with --tls-self-signed) | () |
--timeout |
float | Seconds to wait before timing out if the UI is not shut down | 3600.0 |
--debug |
boolean | Show a structured sync debug log at the bottom of the dashboard (no secret values). | False |
--help, -h |
boolean | Show this message and exit. | False |
Then link from your manual pages.
## Benefits
- ✅ **Always accurate** - Syncs with code automatically
- ✅ **No maintenance** - Updates when CLI changes
- ✅ **Consistent** - Same format everywhere
- ✅ **Complete** - All options documented
- ✅ **Searchable** - Indexed by MkDocs search
## Testing
The build is working! Test with:
```bash
# Build docs
mkdocs build --clean
# Serve locally
mkdocs serve
# Open: http://127.0.0.1:8000
Next Steps¶
- Review examples - Check out the new documentation pages
- Choose a pattern - Decide how to integrate (hybrid recommended)
- Update pages - Add auto-generated sections to existing docs
- Test locally - Verify formatting and layout
- Deploy - Push changes and rebuild docs
Configuration Reference¶
| Option | Description | Example |
|---|---|---|
:module: |
Python module path | secretzero.cli |
:command: |
Command/group name | sync or main |
:prog_name: |
Display name | secretzero sync |
:depth: |
Subcommand levels | 0, 1, or 2 |
:style: |
Output format | table or plain |
:list_subcommands: |
Show subcommand list | True or False |
Resources¶
Support¶
If you encounter issues:
- Check the example pages created
- Review the integration guide
- Verify the module and command names are correct
- Ensure dependencies are installed:
uv sync --extra docs --extra api - Test with
mkdocs serve
File Summary¶
Modified Files¶
pyproject.toml- Added mkdocs-click dependencymkdocs.yml- Added mkdocs_click markdown extension
New Files¶
docs/reference/cli-auto.md- Full example pagedocs/contributing/cli-docs-integration.md- Integration guidedocs/examples/cli-auto-quickstart.md- Quick startdocs/examples/cli-docs-sync-example.md- Hybrid page exampledocs/examples/cli-auto-summary.md- This file
Happy documenting! 📚