Skip to content

CLI Command Reference (Auto-Generated)

This page demonstrates auto-generated CLI documentation using the mkdocs-click plugin.

Complete CLI Reference

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

# Sync with variable file override
secretzero agent sync --var-file dev.szvar

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

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

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

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

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.

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

# Preview plan before applying
secretzero sync --plan

# Machine-readable plan output
secretzero sync --plan --format json

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
--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
--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 static secret values directly in Terraform (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

Individual Command Documentation

sync command

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 Only
secretzero [OPTIONS] COMMAND [ARGS]...

Options:

Text Only
  --version              Show the version and exit.
  -n, --non-interactive  Disable all interactive prompts; error when human
                         input would be required.
  -h, --help             Show this message and exit.

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:

Text Only
  -h, --help  Show this message and exit.

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

# Sync with variable file override
secretzero agent sync --var-file dev.szvar

Usage:

Text Only
secretzero agent 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)
  --dry-run            Preview changes without applying them
  --json               Output results as JSON (machine-readable)
  --interactive        Prompt for manual secrets interactively
  -h, --help           Show this message and exit.

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:

Text Only
  -n, --limit INTEGER   Maximum number of log entries to return
  --offset INTEGER      Number of entries to skip
  -a, --action TEXT     Filter logs by action name
  -r, --resource TEXT   Filter logs by resource name
  --log-file PATH       Path to audit log file
  --format [text|json]  Output format (text or json)
  -h, --help            Show this message and exit.

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:

Text Only
  -h, --help  Show this message and exit.

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:

Text Only
secretzero auth login [OPTIONS]

Options:

Text Only
  -p, --provider TEXT  Provider to authenticate with (e.g. github)  [required]
  --client-id TEXT     OAuth App client ID registered with the provider
                       [required]
  -s, --scopes TEXT    Comma-separated OAuth scopes (default: provider-
                       specific)
  --no-browser         Don't open the browser automatically
  --save-to PATH       Write the token to a file (e.g. .env). Format:
                       KEY=VALUE
  --env-var TEXT       Environment variable name used when writing to --save-
                       to (default: provider-specific)
  -h, --help           Show this message and exit.

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:

Text Only
  -p, --provider TEXT   Provider to check token status for (e.g. github)
                        [required]
  --format [text|json]  Output format
  -h, --help            Show this message and exit.

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:

Text Only
  -f, --file PATH            Path to Secretfile (for show: merge project
                             config; for update: target file)
  --format [text|json|yaml]  Output format (show command)
  -h, --help                 Show this message and exit.

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:

Text Only
  -f, --file PATH            Path to Secretfile (used to merge project config
                             block if present)
  --format [text|json|yaml]  Output format
  -h, --help                 Show this message and exit.

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:

Text Only
  -f, --file PATH  Secretfile path to update (default: Secretfile.yml). Use
                   --user for user config.
  --user           Update user config (~/.config/secretzero/config.yml)
                   instead of Secretfile
  --dry-run        Print what would be written without changing files
  -h, --help       Show this message and exit.

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:

Text Only
  --template-type [basic|aws|azure|vault|kubernetes]
                                  Template type to use for initialization
  -o, --output PATH               Output file path
  -h, --help                      Show this message and exit.

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:

Text Only
  --format [text|json]  Output format (text or json)
  -o, --output PATH     Write suggested Secretfile fragment to file instead of
                        stdout
  -h, --help            Show this message and exit.

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:

Text Only
  -p, --path DIRECTORY            Project root directory to scan
  -o, --output PATH               Output path for Secretfile.detect.yml
                                  (default: <path>/Secretfile.detect.yml)
  --dry-run                       Analyse without writing output files
  --provider [ollama|openai|anthropic|azure_openai]
                                  LLM provider to use for AI-enhanced analysis
  --model TEXT                    LLM model name override
  --local-only                    Restrict to local LLM providers only (e.g.
                                  Ollama)
  --no-llm                        Disable LLM analysis; use pattern matching
                                  only
  -c, --config PATH               Path to secretzero.yml configuration file
  -f, --format [text|json|yaml]   Output summary format
  --threshold FLOAT               Confidence threshold (0.0–1.0) for including
                                  secrets (default from config)
  -v, --verbose                   Show detailed LLM prompts and responses
                                  (text/json output only)
  -h, --help                      Show this message and exit.

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:

Text Only
  -f, --file PATH       Path to Secretfile
  -l, --lockfile PATH   Path to lockfile
  --format [text|json]  Output format (text or json)
  -h, --help            Show this message and exit.

secretzero format

Validate and reformat a Secretfile.yml without losing comments.

Usage:

Text Only
secretzero format [OPTIONS]

Options:

Text Only
  -f, --file PATH  Path to Secretfile.yml to validate and format
  --dry-run        Validate and print formatted YAML to stdout without
                   modifying the file
  --add-missing    Also add missing default values inside the config block
                   (creating it if missing)
  -h, --help       Show this message and exit.

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

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

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

Text Only
  -f, --file PATH                 Path to Secretfile
  -t, --type [flow|detailed|architecture]
                                  Type of graph to generate
  -o, --format [mermaid|terminal|json]
                                  Output format (mermaid, terminal, or json)
  --output PATH                   Output file path (prints to console if not
                                  specified)
  -h, --help                      Show this message and exit.

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:

Text Only
  -f, --file PATH  Path to Secretfile
  --install        Automatically install missing dependencies
  --dry-run        Show what would be installed without installing
  -h, --help       Show this message and exit.

secretzero list

List secrets, providers, targets, or variables from a Secretfile.

Usage:

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

Options:

Text Only
  -h, --help  Show this message and exit.

secretzero list providers

List all providers configured in the Secretfile.

Usage:

Text Only
secretzero list providers [OPTIONS]

Options:

Text Only
  -f, --file PATH       Path to Secretfile
  --format [text|json]  Output format (text or json)
  -h, --help            Show this message and exit.

secretzero list secrets

List all secrets defined in the Secretfile.

Usage:

Text Only
secretzero list secrets [OPTIONS]

Options:

Text Only
  -f, --file PATH       Path to Secretfile
  --format [text|json]  Output format (text or json)
  --filter TEXT         Filter secrets by name substring
  -h, --help            Show this message and exit.

secretzero list targets

List all target destinations across all secrets in the Secretfile.

Usage:

Text Only
secretzero list targets [OPTIONS]

Options:

Text Only
  -f, --file PATH       Path to Secretfile
  --format [text|json]  Output format (text or json)
  -h, --help            Show this message and exit.

secretzero list variables

List all variables defined in the Secretfile.

Usage:

Text Only
secretzero list variables [OPTIONS]

Options:

Text Only
  -f, --file PATH       Path to Secretfile
  --format [text|json]  Output format (text or json)
  --filter TEXT         Filter variables by name substring
  -h, --help            Show this message and exit.

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:

Text Only
  -f, --file PATH       Path to Secretfile
  -l, --lockfile PATH   Path to lockfile
  --fail-on-warning     Exit with error code on policy warnings
  --format [text|json]  Output format (text or json)
  -h, --help            Show this message and exit.

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:

Text Only
  -h, --help  Show this message and exit.

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:

Text Only
  -h, --help  Show this message and exit.

secretzero providers list

List all registered providers.

Shows all provider types available in SecretZero.

Usage:

Text Only
secretzero providers list [OPTIONS]

Options:

Text Only
  -h, --help  Show this message and exit.

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:

Text Only
  -t, --type [generate|retrieve|store|rotate|delete|all]
                                  Filter by capability type
  -h, --help                      Show this message and exit.

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:

Text Only
  --json      Output as JSON instead of formatted text
  -h, --help  Show this message and exit.

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:

Text Only
  -t, --token TEXT  Token to check (falls back to provider-specific env var,
                    e.g. GITHUB_TOKEN)
  -h, --help        Show this message and exit.

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:

Text Only
  -f, --file PATH       Path to Secretfile
  -v, --var-file PATH   Path to .szvar variable file(s) to merge (can be
                        specified multiple times)
  --format [yaml|json]  Output format (yaml or json)
  -o, --output PATH     Write output to file instead of stdout
  -h, --help            Show this message and exit.

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.

Usage:

Text Only
secretzero rotate [OPTIONS] [SECRET_NAME]

Options:

Text Only
  -f, --file PATH       Path to Secretfile
  -l, --lockfile PATH   Path to lockfile
  --force               Force rotation even if not due
  --dry-run             Show what would be rotated without making changes
  --show-input          Show secret input as plain text when prompting
                        (default: masked)
  --format [text|json]  Output format (text or json)
  -h, --help            Show this message and exit.

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:

Text Only
  -o, --output-dir 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)
  --with-generator TEXT  Generator kind to include (can be repeated, e.g.
                         --with-generator my_token)
  --description TEXT     Short description for the provider
  -h, --help             Show this message and exit.

secretzero schema

Schema utilities for Secretfile.

Usage:

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

Options:

Text Only
  -h, --help  Show this message and exit.

secretzero schema export

Export JSON Schema for Secretfile.yml.

Usage:

Text Only
secretzero schema export [OPTIONS]

Options:

Text Only
  -o, --output PATH  Output file path or '-' for stdout
  -h, --help         Show this message and exit.

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:

Text Only
  -t, --type TEXT  Show details for a specific secret type
  -v, --verbose    Show detailed information
  -h, --help       Show this message and exit.

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:

Text Only
  -f, --file PATH      Path to Secretfile
  -l, --lockfile PATH  Path to lockfile
  -d, --detailed       Show detailed configuration and sub-fields
  -h, --help           Show this message and exit.

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:

Text Only
  -f, --file PATH       Path to Secretfile
  -l, --lockfile PATH   Path to lockfile
  -v, --verbose         Show detailed information including target hashes
  --format [text|json]  Output format (text or json)
  -h, --help            Show this message and exit.

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

# Preview plan before applying
secretzero sync --plan

# Machine-readable plan output
secretzero sync --plan --format json

Usage:

Text Only
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)
  --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
  -h, --help            Show this message and exit.

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:

Text Only
  -f, --file PATH                 Path to Secretfile
  -v, --var-file PATH             Path to .szvar variable file(s) (can be
                                  specified multiple times)
  -o, --output-dir PATH           Directory to write generated Terraform files
  --format [hcl|json]             Terraform output format (hcl or json)
  --include-static-secrets / --no-include-static-secrets
                                  Include static secret values directly in
                                  Terraform (may embed secrets in code).
  --dry-run                       Show a summary of what would be generated
                                  without writing files
  -h, --help                      Show this message and exit.

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:

Text Only
  -f, --file PATH     Path to Secretfile
  --include-profiles  Test each defined authentication profile for providers
  -v, --verbose       Show detailed error information including stack traces
  -h, --help          Show this message and exit.

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:

Text Only
  -f, --file PATH       Path to Secretfile
  -v, --var-file PATH   Path to .szvar variable file(s) to validate with (can
                        be specified multiple times)
  --format [text|json]  Output format (text or json)
  -h, --help            Show this message and exit.

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:

Text Only
  --output-format [text|json]  Output format
  -h, --help                   Show this message and exit.

validate command

Full details for the validate subcommand:

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:

Text Only
  -f, --file PATH       Path to Secretfile
  -v, --var-file PATH   Path to .szvar variable file(s) to validate with (can
                        be specified multiple times)
  --format [text|json]  Output format (text or json)
  -h, --help            Show this message and exit.

rotate command

Full details for the rotate subcommand:

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.

Usage:

Text Only
secretzero rotate [OPTIONS] [SECRET_NAME]

Options:

Text Only
  -f, --file PATH       Path to Secretfile
  -l, --lockfile PATH   Path to lockfile
  --force               Force rotation even if not due
  --dry-run             Show what would be rotated without making changes
  --show-input          Show secret input as plain text when prompting
                        (default: masked)
  --format [text|json]  Output format (text or json)
  -h, --help            Show this message and exit.

Usage Notes

The documentation above is automatically generated from the Click command definitions in src/secretzero/cli.py. Any changes to the CLI commands, options, or help text will automatically be reflected here.

Customization Options

The mkdocs-click plugin supports several options:

  • :depth: - How many subcommand levels to include (0 = command only, 1 = command + subcommands, 2 = all levels)
  • :style: - Display style (plain, table, or custom)
  • :list_subcommands: - Whether to list subcommands (default: True)
  • :prog_name: - The program name to display in usage examples

Integration Examples

Embed in Existing Pages

You can embed auto-generated CLI docs within your existing documentation:

Markdown
# Sync Command

Some introductory text about the sync command...

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

    # Preview plan before applying
    secretzero sync --plan

    # Machine-readable plan output
    secretzero sync --plan --format json

**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)
  --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
  -h, --help            Show this message and exit.

Additional Notes

Your custom notes and examples here...

Text Only
#### Create Command-Specific Pages

For each command, create a dedicated page with:

1. High-level overview
2. Auto-generated reference
3. Detailed examples
4. Best practices

#### Table-Style Output

Use `:style: table` for a clean, scannable reference:

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

# Sync with variable file override
secretzero agent sync --var-file dev.szvar

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

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

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

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

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.

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

# Preview plan before applying
secretzero sync --plan

# Machine-readable plan output
secretzero sync --plan --format json

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
--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
--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 static secret values directly in Terraform (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

```

Benefits

  • ✅ Always up-to-date: Docs sync automatically with code changes
  • ✅ Consistent: Same format across all commands
  • ✅ Complete: All options, arguments, and help text included
  • ✅ Maintainable: Single source of truth (your Click commands)
  • ✅ Searchable: Full-text search works on auto-generated content