Skip to main content

​
CLI Reference

Complete guide to the FailZero CLI (fz).

​
Installation

npm install -g @failzero/cli
Verify installation: 
fz version

​
Authentication

​
fz auth login

Authenticate with FailZero. Opens browser for OAuth login. 
fz auth login
After successful authentication, your token is stored securely in the system keychain.

​
fz auth logout

Remove stored credentials. 
fz auth logout

​
fz auth status

Check current authentication status. 
fz auth status

​
DR Plan Management

​
fz init

Initialize a new DR plan configuration file. 
fz init
Interactive prompts will guide you through:
  • Cloud provider selection (GCP, AWS)
  • Project/account configuration
  • Region selection
Creates a dr.yaml file in the current directory. Options:
FlagDescription
--providerSkip prompt: gcp or aws
--projectGCP project ID
--accountAWS account ID
--regionCloud region
Example: 
fz init --provider gcp --project my-project --region us-west1

​
fz validate

Validate a DR plan configuration file. 
fz validate [file]
Arguments:
ArgumentDescriptionDefault
filePath to DR plan filedr.yaml
Example: 
fz validate production-dr.yaml
Validates:
  • YAML syntax
  • Required fields
  • Provider configuration
  • Monitor definitions
  • Failover step references

​
fz deploy

Deploy a DR plan to FailZero. 
fz deploy [file]
Arguments:
ArgumentDescriptionDefault
filePath to DR plan filedr.yaml
Options:
FlagDescription
--dry-runValidate without deploying
--forceSkip confirmation prompt
Example: 
# Deploy with confirmation
fz deploy production-dr.yaml

# Deploy without confirmation
fz deploy production-dr.yaml --force

# Validate only
fz deploy production-dr.yaml --dry-run

​
Monitoring & Status

​
fz status

Check the status of a deployed DR plan. 
fz status <plan-name>
Arguments:
ArgumentDescription
plan-nameName of the deployed plan
Output includes:
  • Plan status (active, paused, error)
  • Monitor health
  • Last check time
  • Agent connection status
Example: 
fz status production-api

​
fz list

List all deployed DR plans. 
fz list
Options:
FlagDescription
--jsonOutput as JSON

​
Failover Operations

​
fz failover

Trigger a failover for a DR plan. 
fz failover <plan-name> [options]
Arguments:
ArgumentDescription
plan-nameName of the deployed plan
Options:
FlagDescription
--reasonReason for failover (required)
--stepExecute specific step only
--dry-runShow what would happen
--forceSkip confirmation
Examples: 
# Standard failover
fz failover production-api --reason "Primary region outage"

# Test specific step
fz failover production-api --step promote-db --reason "Testing DB promotion"

# Dry run
fz failover production-api --reason "Test" --dry-run
Failover executes real infrastructure changes. Always test in non-production first.

​
fz approve

Approve a pending failover (when confirmation is required). 
fz approve <failover-id>
Arguments:
ArgumentDescription
failover-idID of the pending failover
Example: 
fz approve fo_abc123def456

​
fz cancel

Cancel a pending or in-progress failover. 
fz cancel <failover-id>
Arguments:
ArgumentDescription
failover-idID of the failover to cancel

​
History

​
fz history

View failover history for a DR plan. 
fz history <plan-name>
Arguments:
ArgumentDescription
plan-nameName of the DR plan
Options:
FlagDescription
--limit <n>Number of events to show (default: 10)
Example: 
# Show last 10 failovers
fz history production-api

# Show last 50 failovers
fz history production-api --limit 50
Output includes:
  • Timestamp
  • Trigger type (manual/automatic)
  • Who triggered it
  • Duration
  • Success/failure status

​
Agent Management

​
fz agent deploy

Deploy a FailZero agent to your cloud provider. Interactive wizard guides you through the setup. 
fz agent deploy
Options:
FlagDescription
-p, --provider <provider>Cloud provider (gcp or aws)
-n, --name <name>Agent name
--project <project>GCP Project ID
--region <region>Cloud region
--no-interactiveSkip interactive prompts
Examples: 
# Interactive deployment (recommended)
fz agent deploy

# Non-interactive GCP deployment
fz agent deploy --provider gcp --project my-project --region us-west1 --name gcp-agent

# Non-interactive AWS deployment
fz agent deploy --provider aws --region us-east-1 --name aws-agent
What it does:
  1. Creates an agent token via the FailZero API
  2. For GCP: Deploys to Cloud Run with proper environment variables
  3. For AWS: Creates ECS Fargate service with task definition
Requires gcloud CLI (GCP) or aws CLI (AWS) to be installed and authenticated.

​
fz agent list

List all agents and their connection status. Alias: fz agent status 
fz agent list
Output includes:
  • Agent name and ID
  • Connection status (Connected/Inactive)
  • Token prefix
  • Last seen timestamp

​
fz agent revoke

Revoke an agent token. 
fz agent revoke <agent-id>
Arguments:
ArgumentDescription
agent-idID of the agent to revoke

​
Configuration File

​
fz config

View or modify CLI configuration. 
# View current config
fz config

# Set API URL (for self-hosted)
fz config set api-url https://api.your-failzero.com

​
Global Options

These options work with all commands:
FlagDescription
--helpShow help for command
--versionShow CLI version
--jsonOutput as JSON (where supported)
--quietSuppress non-essential output

​
Exit Codes

CodeDescription
0Success
1General error
2Configuration error
3Authentication error
4Validation error
5Network error

​
Environment Variables

VariableDescription
FAILZERO_API_URLOverride API endpoint
FAILZERO_TOKENUse token instead of keychain
FAILZERO_LANDING_URLOverride landing page URL

​
Examples

​
Complete Workflow

# 1. Authenticate
fz auth login

# 2. Create DR plan
fz init --provider gcp --project my-project

# 3. Edit dr.yaml with your configuration
vim dr.yaml

# 4. Validate
fz validate

# 5. Deploy
fz deploy

# 6. Check status
fz status my-plan

# 7. Test failover (dry run)
fz failover my-plan --reason "Testing" --dry-run

# 8. Real failover when needed
fz failover my-plan --reason "Primary outage detected"

​
Next Steps

Example Plans

Real-world DR configurations

Quickstart

End-to-end setup guide