Quick Start: Auto-Generated CLI Documentation¶

This guide gets you started with automatic CLI documentation generation in 5 minutes.

Installation¶

Bash

# Install mkdocs-click
uv sync --extra docs

# Or with pip
pip install mkdocs-click

✅ Already configured in your mkdocs.yml and pyproject.toml!

Usage¶

Add this to any markdown file in your docs:

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`

Text Only

That's it! The CLI documentation will be auto-generated from your Click commands.

## Common Patterns

### Pattern 1: Full CLI Tree

Show all commands and subcommands:

```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:

Text Only

secretzero agent [OPTIONS] COMMAND [ARGS]...

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:

Text Only

# 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:

Text Only

secretzero agent 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	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:

Text Only

# 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:

Text Only

secretzero audit [OPTIONS]

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:

Text Only

secretzero auth [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`, `-h`	boolean	Show this message and exit.	`False`

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:

Text Only

secretzero auth login [OPTIONS]

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:

Text Only

secretzero auth status [OPTIONS]

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:

Text Only

secretzero config [OPTIONS] COMMAND [ARGS]...

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:

Text Only

secretzero config show [OPTIONS]

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:

Text Only

secretzero config update [OPTIONS] KEY_PATH VALUE

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:

Text Only

secretzero create [OPTIONS]

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:

Text Only

# 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:

Text Only

secretzero detect [OPTIONS] [DIRECTORY]

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:

Text Only

secretzero discover [OPTIONS]

Options:

Name	Type	Description	Default
`--path`, `-p`	directory	Project root directory to scan	`.`
`--output`, `-o`	path	Output path for Secretfile.detect.yml (default: /Secretfile.detect.yml)	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:

Text Only

secretzero drift [OPTIONS] [SECRET_NAME]

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:

Text Only

secretzero format [OPTIONS]

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:

Text Only

secretzero get [OPTIONS]

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:

Text Only

# 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:

Text Only

secretzero graph [OPTIONS]

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:

Text Only

secretzero import [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 (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:

Text Only

secretzero init [OPTIONS]

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:

Text Only

secretzero list [OPTIONS] COMMAND [ARGS]...

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:

Text Only

secretzero list providers [OPTIONS]

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:

Text Only

secretzero list secrets [OPTIONS]

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:

Text Only

secretzero list targets [OPTIONS]

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:

Text Only

secretzero list variables [OPTIONS]

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:

Text Only

secretzero policy [OPTIONS]

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:

Text Only

secretzero providers [OPTIONS] COMMAND [ARGS]...

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:

Text Only

secretzero providers capabilities [OPTIONS] PROVIDER_TYPE

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:

Text Only

secretzero providers list [OPTIONS]

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:

Text Only

secretzero providers methods [OPTIONS] PROVIDER_TYPE

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:

Text Only

secretzero providers schema [OPTIONS] PROVIDER_TYPE METHOD_NAME

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:

Text Only

# 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:

Text Only

secretzero providers token-info [OPTIONS] [PROVIDER_TYPE]

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:

Text Only

# 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:

Text Only

secretzero render [OPTIONS]

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:

Text Only

secretzero rotate [OPTIONS] [SECRET_NAME]

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:

Text Only

secretzero scaffold-bundle [OPTIONS] NAME

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:

Text Only

secretzero schema [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`, `-h`	boolean	Show this message and exit.	`False`

secretzero schema export¶

Export JSON Schema for Secretfile.yml.

Usage:

Text Only

secretzero schema export [OPTIONS]

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:

Text Only

secretzero secret-types [OPTIONS]

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:

Text Only

secretzero show [OPTIONS] [SECRET_NAME]

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:

Text Only

secretzero status [OPTIONS]

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:

Text Only

# 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 Only

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`

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:

Text Only

secretzero terraform [OPTIONS]

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:

Text Only

secretzero test [OPTIONS]

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:

Text Only

secretzero validate [OPTIONS]

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:

Text Only

secretzero validate-bundle [OPTIONS] PATH

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:

Text Only

secretzero web [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	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`

Text Only

### Pattern 2: Single Command

Document one specific 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:

Text Only

  -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.

Text Only

### Pattern 3: Hybrid (Manual + Auto)

Combine manual docs with auto-generated reference:

```markdown
# secretzero sync

Your manual introduction and examples here...

## 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¶

Your additional examples and best practices...

Text Only

## Test It

```bash
# Start local docs server
mkdocs serve

# Open browser to http://127.0.0.1:8000
# Navigate to your CLI documentation pages

Configuration Quick 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-2)	`0` = command only `1` = + subcommands `2` = all levels
`:style:`	Output format	`table` or `plain`

Examples¶

See these pages for complete examples:

Benefits¶

✅ Always up-to-date with your code
✅ No manual maintenance needed
✅ Consistent formatting
✅ Complete option coverage
✅ Searchable documentation

Next Steps¶

Review examples in docs/reference/cli-auto.md
Update existing pages following patterns in docs/contributing/cli-docs-integration.md
Test locally with mkdocs serve
Customize styling and depth as needed

Quick Start: Auto-Generated CLI Documentation¶

Installation¶

Usage¶

secretzero agent¶

secretzero agent sync¶

secretzero audit¶

secretzero auth¶

secretzero auth login¶

secretzero auth status¶

secretzero config¶

secretzero config show¶

secretzero config update¶

secretzero create¶

secretzero detect¶

secretzero discover¶

secretzero drift¶

secretzero format¶

secretzero get¶

secretzero graph¶

secretzero import¶

secretzero init¶

secretzero list¶

secretzero list providers¶

secretzero list secrets¶

secretzero list targets¶

secretzero list variables¶

secretzero policy¶

secretzero providers¶

secretzero providers capabilities¶

secretzero providers list¶

secretzero providers methods¶

secretzero providers schema¶

secretzero providers token-info¶

secretzero render¶

secretzero rotate¶

secretzero scaffold-bundle¶

secretzero schema¶

secretzero schema export¶

secretzero secret-types¶

secretzero show¶

secretzero status¶

secretzero sync¶

secretzero terraform¶

secretzero test¶

secretzero validate¶

secretzero validate-bundle¶

secretzero web¶

More Examples¶

Configuration Quick Reference¶

Examples¶

Benefits¶

Next Steps¶

Documentation¶