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

# CLI

> Use the Inbox Zero API CLI from npm or npx.

Use the Inbox Zero API CLI when you want a thin wrapper around the public API for scripts, bots, or local automation.

The package is published to npm as `@inbox-zero/api`, and the executable name is `inbox-zero-api`.

## Run with npx

Requires Node.js `18+`.

```bash theme={null}
npx @inbox-zero/api --help
```

You can also install it globally:

```bash theme={null}
npm install -g @inbox-zero/api
```

## Configure access

The CLI reads configuration in this order:

1. Command flags
2. Environment variables
3. `~/.inbox-zero-api/config.json`

Supported environment variables:

* `INBOX_ZERO_API_KEY`
* `INBOX_ZERO_BASE_URL` for self-hosted or custom API deployments

Example:

```bash theme={null}
inbox-zero-api rules list
```

`base-url` is optional. The CLI defaults to `https://www.getinboxzero.com` and only needs an override for self-hosted or custom deployments.

Set `INBOX_ZERO_API_KEY` in your shell or secret manager before running commands. Avoid passing API keys as CLI arguments because they can leak into shell history and process listings.

## Common commands

List rules:

```bash theme={null}
inbox-zero-api rules list
inbox-zero-api rules list --json
```

Get a rule:

```bash theme={null}
inbox-zero-api rules get rule_123 --json
```

Create a rule from JSON:

```bash theme={null}
inbox-zero-api rules create --file rule.json
cat rule.json | inbox-zero-api rules create --file -
```

Update a rule from JSON:

```bash theme={null}
cat rule.json | inbox-zero-api rules update rule_123 --file -
```

Delete a rule:

```bash theme={null}
inbox-zero-api rules delete rule_123
```

Read stats:

```bash theme={null}
inbox-zero-api stats by-period --period week --json
inbox-zero-api stats response-time --json
```

Fetch the live OpenAPI document:

```bash theme={null}
inbox-zero-api openapi --json
```

For bots, prefer `--json` so the output is stable and machine-readable.