CLI Reference

Complete guide to the FailZero CLI (fz).

Installation

npm install -g @failzero/cli

Verify installation:

fz version

Authentication

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:

Flag	Description
`--provider`	Skip prompt: `gcp` or `aws`
`--project`	GCP project ID
`--account`	AWS account ID
`--region`	Cloud region

Example:

fz init --provider gcp --project my-project --region us-west1

fz validate

Validate a DR plan configuration file.

fz validate [file]

Arguments:

Argument	Description	Default
`file`	Path to DR plan file	`dr.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:

Argument	Description	Default
`file`	Path to DR plan file	`dr.yaml`

Options:

Flag	Description
`--dry-run`	Validate without deploying
`--force`	Skip 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:

Argument	Description
`plan-name`	Name 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:

Flag	Description
`--json`	Output as JSON

Failover Operations

fz failover

Trigger a failover for a DR plan.

fz failover <plan-name> [options]

Arguments:

Argument	Description
`plan-name`	Name of the deployed plan

Options:

Flag	Description
`--reason`	Reason for failover (required)
`--step`	Execute specific step only
`--dry-run`	Show what would happen
`--force`	Skip 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:

Argument	Description
`failover-id`	ID of the pending failover

Example:

fz approve fo_abc123def456

fz cancel

Cancel a pending or in-progress failover.

fz cancel <failover-id>

Arguments:

Argument	Description
`failover-id`	ID of the failover to cancel

History

fz history

View failover history for a DR plan.

fz history <plan-name>

Arguments:

Argument	Description
`plan-name`	Name of the DR plan

Options:

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

Flag	Description
`-p, --provider <provider>`	Cloud provider (`gcp` or `aws`)
`-n, --name <name>`	Agent name
`--project <project>`	GCP Project ID
`--region <region>`	Cloud region
`--no-interactive`	Skip 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:

Creates an agent token via the FailZero API
For GCP: Deploys to Cloud Run with proper environment variables
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:

Argument	Description
`agent-id`	ID 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:

Flag	Description
`--help`	Show help for command
`--version`	Show CLI version
`--json`	Output as JSON (where supported)
`--quiet`	Suppress non-essential output

Exit Codes

Code	Description
`0`	Success
`1`	General error
`2`	Configuration error
`3`	Authentication error
`4`	Validation error
`5`	Network error

Environment Variables

Variable	Description
`FAILZERO_API_URL`	Override API endpoint
`FAILZERO_TOKEN`	Use token instead of keychain
`FAILZERO_LANDING_URL`	Override 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"

CLI Reference

CLI Reference

Installation

Authentication

fz auth logout

fz auth status

DR Plan Management

fz init

fz validate

fz deploy

Monitoring & Status

fz status

fz list

Failover Operations

fz failover

fz approve

fz cancel

History

fz history

Agent Management

fz agent deploy

fz agent list

fz agent revoke

Configuration File

fz config

Global Options

Exit Codes

Environment Variables

Examples

Complete Workflow

Next Steps

Example Plans

Quickstart

​CLI Reference

​Installation

​Authentication

​fz auth login

​fz auth logout

​fz auth status

​DR Plan Management

​fz init

​fz validate

​fz deploy

​Monitoring & Status

​fz status

​fz list

​Failover Operations

​fz failover

​fz approve

​fz cancel

​History

​fz history

​Agent Management

​fz agent deploy

​fz agent list

​fz agent revoke

​Configuration File

​fz config

​Global Options

​Exit Codes

​Environment Variables

​Examples

​Complete Workflow

​Next Steps

Example Plans

Quickstart

CLI Reference

Installation

Authentication

fz auth login

fz auth logout

fz auth status

DR Plan Management

fz init

fz validate

fz deploy

Monitoring & Status

fz status

fz list

Failover Operations

fz failover

fz approve

fz cancel

History

fz history

Agent Management

fz agent deploy

fz agent list

fz agent revoke

Configuration File

fz config

Global Options

Exit Codes

Environment Variables

Examples

Complete Workflow

Next Steps