> ## Documentation Index
> Fetch the complete documentation index at: https://docs.failzero.io/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> FailZero CLI commands

# CLI Reference

Complete guide to the FailZero CLI (`fz`).

## Installation

```bash theme={null}
npm install -g @failzero/cli
```

Verify installation:

```bash theme={null}
fz version
```

## Authentication

### fz auth login

Authenticate with FailZero. Opens browser for OAuth login.

```bash theme={null}
fz auth login
```

After successful authentication, your token is stored securely in the system keychain.

### fz auth logout

Remove stored credentials.

```bash theme={null}
fz auth logout
```

### fz auth status

Check current authentication status.

```bash theme={null}
fz auth status
```

## DR Plan Management

### fz init

Initialize a new DR plan configuration file.

```bash theme={null}
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:**

```bash theme={null}
fz init --provider gcp --project my-project --region us-west1
```

### fz validate

Validate a DR plan configuration file.

```bash theme={null}
fz validate [file]
```

**Arguments:**

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

**Example:**

```bash theme={null}
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.

```bash theme={null}
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:**

```bash theme={null}
# 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.

```bash theme={null}
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:**

```bash theme={null}
fz status production-api
```

### fz list

List all deployed DR plans.

```bash theme={null}
fz list
```

**Options:**

| Flag     | Description    |
| -------- | -------------- |
| `--json` | Output as JSON |

## Failover Operations

### fz failover

Trigger a failover for a DR plan.

```bash theme={null}
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:**

```bash theme={null}
# 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
```

<Warning>
  Failover executes real infrastructure changes. Always test in non-production first.
</Warning>

### fz approve

Approve a pending failover (when confirmation is required).

```bash theme={null}
fz approve <failover-id>
```

**Arguments:**

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

**Example:**

```bash theme={null}
fz approve fo_abc123def456
```

### fz cancel

Cancel a pending or in-progress failover.

```bash theme={null}
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.

```bash theme={null}
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:**

```bash theme={null}
# 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.

```bash theme={null}
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:**

```bash theme={null}
# 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

<Info>
  Requires `gcloud` CLI (GCP) or `aws` CLI (AWS) to be installed and authenticated.
</Info>

### fz agent list

List all agents and their connection status. Alias: `fz agent status`

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
# 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

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="Example Plans" icon="code" href="/guides/examples">
    Real-world DR configurations
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    End-to-end setup guide
  </Card>
</CardGroup>