> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.withpaygent.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withpaygent.com/_mcp/server.

# Global Options

> Flags, output formats, and exit codes available on every command.

## Global Flags

```bash
paygent agent list --output json --timeout 60s
```

| Flag                     | Description                                              |
| ------------------------ | -------------------------------------------------------- |
| `-o`, `--output <fmt>`   | `table`, `json`, `yaml`, or `csv`.                       |
| `--profile <name>`       | Configuration profile to use.                            |
| `--org <id>`             | Organization to act on.                                  |
| `--api-url <url>`        | Dashboard API base URL.                                  |
| `--tracking-url <url>`   | Tracking API base URL.                                   |
| `--app-url <url>`        | Web app base URL, used by browser login.                 |
| `--timeout <dur>`        | Per-request timeout. Default `30s`.                      |
| `--no-input`             | Never prompt; a missing value becomes an error.          |
| `--debug`                | Full request and response detail, with secrets redacted. |
| `-v`, `--verbose`        | Method, path, status, and duration.                      |
| `--color` / `--no-color` | Control colored output.                                  |
| `--help`                 | Show command help.                                       |
| `--version`              | Show the CLI version.                                    |

## Output Formats

Output defaults to a table on a terminal and **JSON when piped**, so scripts need no extra flag.

```bash
paygent agent list | jq -r '.[].externalId'
paygent usage cost --customer acme --output csv > cost.csv
```

## Exit Codes

```bash
paygent exit-codes
```

| Code  | Name        | Meaning                                    |
| ----- | ----------- | ------------------------------------------ |
| `0`   | OK          | Success.                                   |
| `1`   | ERROR       | Generic failure.                           |
| `2`   | USAGE       | Bad flags or arguments.                    |
| `3`   | AUTH        | Not logged in, or credentials expired.     |
| `4`   | PERMISSION  | Authorization failure.                     |
| `5`   | NOT\_FOUND  | Resource does not exist.                   |
| `6`   | VALIDATION  | Invalid input.                             |
| `7`   | CONFLICT    | Already exists.                            |
| `8`   | RATE\_LIMIT | Too many requests.                         |
| `9`   | NETWORK     | DNS, connection, timeout, or TLS failure.  |
| `10`  | SERVER      | Server error.                              |
| `11`  | UNAVAILABLE | Endpoint not available in this deployment. |
| `130` | INTERRUPTED | Cancelled with Ctrl-C.                     |

## Diagnostics

```bash
paygent doctor                  # check environment and configuration
paygent doctor --connectivity   # also verify API reachability and latency
paygent version
```

## Shell Completion

#### zsh

```bash
paygent completion zsh > "${fpath[1]}/_paygent"
```

#### bash

```bash
paygent completion bash > /etc/bash_completion.d/paygent
```

#### fish

```bash
paygent completion fish > ~/.config/fish/completions/paygent.fish
```