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:

secretzero [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--version`	boolean	Show the version and exit.	`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:

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

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

Create a new Secretfile from a template.

This command generates a starter Secretfile.yml with example configurations for different provider types.

Usage:

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:

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

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

Detect drift between lockfile and actual targets.

This command checks if secrets have been modified outside of SecretZero's control.

Usage:

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

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

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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.

Currently supports GitHub tokens. Displays OAuth scopes, user information, and token capabilities.

Examples:

# Check GITHUB_TOKEN environment variable
secretzero providers token-info

# Check specific token
secretzero providers token-info --token ghp_xxxxx

# Explicitly specify provider
secretzero providers token-info --provider github

Usage:

secretzero providers token-info [OPTIONS]

Options:

Name	Type	Description	Default
`--provider`, `-p`	choice (`github`)	Provider to check token permissions for	`github`
`--token`, `-t`	text	Token to check (uses GITHUB_TOKEN env var if not provided)	`Sentinel.UNSET`
`--help`, `-h`	boolean	Show this message and exit.	`False`

secretzero render¶

Render the final Secretfile configuration with variables interpolated.

This command displays or saves the complete Secretfile configuration after merging variable files and applying variable interpolation. This is useful for debugging variable issues or understanding the final configuration.

Variable files (.szvar) are merged in order with later files taking precedence.

Examples:

# Render to stdout
secretzero render

# Render with variable file
secretzero render --var-file dev.szvar

# Render with multiple variable files
secretzero render --var-file base.szvar --var-file dev.szvar

# Render to file in JSON format
secretzero render --var-file dev.szvar --format json --output rendered.json

Usage:

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:

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

Schema utilities for Secretfile.

Usage:

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:

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:

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:

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:

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.

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:

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

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:

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`

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:

secretzero [OPTIONS] COMMAND [ARGS]...

Options:

  --version   Show the version and exit.
  -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:

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

secretzero audit [OPTIONS]

Options:

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

Create a new Secretfile from a template.

This command generates a starter Secretfile.yml with example configurations for different provider types.

Usage:

secretzero create [OPTIONS]

Options:

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

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

secretzero detect [OPTIONS] [DIRECTORY]

Options:

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

Detect drift between lockfile and actual targets.

This command checks if secrets have been modified outside of SecretZero's control.

Usage:

secretzero drift [OPTIONS] [SECRET_NAME]

Options:

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

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

secretzero graph [OPTIONS]

Options:

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

secretzero init [OPTIONS]

Options:

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

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

Options:

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

secretzero list providers¶

List all providers configured in the Secretfile.

Usage:

secretzero list providers [OPTIONS]

Options:

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

secretzero list secrets [OPTIONS]

Options:

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

secretzero list targets [OPTIONS]

Options:

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

secretzero list variables [OPTIONS]

Options:

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

secretzero policy [OPTIONS]

Options:

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

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

Options:

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

secretzero providers capabilities [OPTIONS] PROVIDER_TYPE

Options:

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

secretzero providers list¶

List all registered providers.

Shows all provider types available in SecretZero.

Usage:

secretzero providers list [OPTIONS]

Options:

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

secretzero providers methods [OPTIONS] PROVIDER_TYPE

Options:

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

secretzero providers schema [OPTIONS] PROVIDER_TYPE METHOD_NAME

Options:

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

Currently supports GitHub tokens. Displays OAuth scopes, user information, and token capabilities.

Examples:

# Check GITHUB_TOKEN environment variable
secretzero providers token-info

# Check specific token
secretzero providers token-info --token ghp_xxxxx

# Explicitly specify provider
secretzero providers token-info --provider github

Usage:

secretzero providers token-info [OPTIONS]

Options:

  -p, --provider [github]  Provider to check token permissions for
  -t, --token TEXT         Token to check (uses GITHUB_TOKEN env var if not
                           provided)
  -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:

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

secretzero render [OPTIONS]

Options:

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

secretzero rotate [OPTIONS] [SECRET_NAME]

Options:

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

Schema utilities for Secretfile.

Usage:

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

Options:

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

secretzero schema export¶

Export JSON Schema for Secretfile.yml.

Usage:

secretzero schema export [OPTIONS]

Options:

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

secretzero secret-types [OPTIONS]

Options:

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

secretzero show [OPTIONS] [SECRET_NAME]

Options:

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

secretzero status [OPTIONS]

Options:

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

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:

secretzero sync [OPTIONS]

Options:

  -f, --file PATH       Path to Secretfile
  -l, --lockfile PATH   Path to lockfile
  -v, --var-file PATH   Path to .szvar variable file(s) to merge (can be
                        specified multiple times)
  --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 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:

secretzero test [OPTIONS]

Options:

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

secretzero validate [OPTIONS]

Options:

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

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:

secretzero validate [OPTIONS]

Options:

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

secretzero rotate [OPTIONS] [SECRET_NAME]

Options:

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

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

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:

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

#### 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`
`--help`, `-h`	boolean	Show this message and exit.	`False`

secretzero audit¶

View API audit logs.

Displays audit log entries recorded by the SecretZero API. Logs are written to a file when the API server is running.

Examples:

# Show recent audit logs
secretzero audit

# Filter by action
secretzero audit --action sync

# Filter by resource
secretzero audit --resource secrets

# Show in JSON format
secretzero audit --format json

# Show last 100 entries
secretzero audit --limit 100

Usage:

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

Create a new Secretfile from a template.

This command generates a starter Secretfile.yml with example configurations for different provider types.

Usage:

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:

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

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

Detect drift between lockfile and actual targets.

This command checks if secrets have been modified outside of SecretZero's control.

Usage:

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

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

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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.

Currently supports GitHub tokens. Displays OAuth scopes, user information, and token capabilities.

Examples:

# Check GITHUB_TOKEN environment variable
secretzero providers token-info

# Check specific token
secretzero providers token-info --token ghp_xxxxx

# Explicitly specify provider
secretzero providers token-info --provider github

Usage:

secretzero providers token-info [OPTIONS]

Options:

Name	Type	Description	Default
`--provider`, `-p`	choice (`github`)	Provider to check token permissions for	`github`
`--token`, `-t`	text	Token to check (uses GITHUB_TOKEN env var if not provided)	`Sentinel.UNSET`
`--help`, `-h`	boolean	Show this message and exit.	`False`

secretzero render¶

Render the final Secretfile configuration with variables interpolated.

This command displays or saves the complete Secretfile configuration after merging variable files and applying variable interpolation. This is useful for debugging variable issues or understanding the final configuration.

Variable files (.szvar) are merged in order with later files taking precedence.

Examples:

# Render to stdout
secretzero render

# Render with variable file
secretzero render --var-file dev.szvar

# Render with multiple variable files
secretzero render --var-file base.szvar --var-file dev.szvar

# Render to file in JSON format
secretzero render --var-file dev.szvar --format json --output rendered.json

Usage:

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:

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

Schema utilities for Secretfile.

Usage:

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:

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:

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:

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:

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.

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:

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

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:

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`

```

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