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

# CLI reference

> Install the Ardent CLI, understand command groups, and automate branch workflows

The Ardent CLI is the fastest way to connect a Postgres source, create isolated database branches, and hand safe branch URLs to apps, tests, and coding agents.

Use the CLI when you are working at a terminal. Use the [API](/api/overview) when you are building your own automation or platform integration.

## Install

```bash theme={null}
npm install -g ardent-cli
```

The CLI runs on modern Node.js LTS releases. We recommend Node 18 or newer.

Check your install:

```bash theme={null}
ardent --version
ardent --help
```

You can also ask any command for help:

```bash theme={null}
ardent connector --help
ardent branch create --help
```

## How the CLI is organized

| Group                                            | What it manages                                  |
| ------------------------------------------------ | ------------------------------------------------ |
| `ardent login`, `ardent logout`, `ardent status` | Your local session and active workspace          |
| `ardent project ...`                             | Projects inside your organization                |
| `ardent connector ...`                           | Source databases Ardent can replicate and branch |
| `ardent branch ...`                              | Isolated database branches and connection URLs   |
| `ardent settings ...`                            | Per-connector defaults for future branches       |
| `ardent invite ...`, `ardent org ...`            | Team invites, members, and roles                 |

## The selection model

The CLI keeps track of the current project, connector, and branch for you:

1. A **project** groups related connectors and branches.
2. A **connector** points to one Postgres source server.
3. A **branch** is an isolated database created from that connector.

After login, Ardent auto-selects your project and connector if there is only one clear choice. If your organization has more than one, select explicitly:

```bash theme={null}
ardent project switch my-project
ardent connector switch prod-db
ardent branch switch my-feature
```

In CI, always switch project and connector explicitly. That keeps automation stable even if your personal defaults change.

## Human output and automation output

Most commands print friendly terminal output by default. Branch commands also support automation-friendly output:

```bash theme={null}
ardent branch create pr-123 --print-url
ardent branch info my-feature --format json
```

Use `--print-url` when a script needs only the connection URL. Use `--format json` when you want a stable object with the branch name, status, service type, connector ID, and URL.

## Environment variables

| Variable         | Use it for                                                                                                                                                                                                                                                                                           |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ARDENT_TOKEN`   | Authenticate in CI or other headless environments without running `ardent login`. If this machine already has a stored login token, the stored token is used first; run `ardent logout` in that environment if you want `ARDENT_TOKEN` to be the only credential source.                             |
| `ARDENT_API_URL` | Override the API endpoint. Defaults to `https://api.tryardent.com`. If a stored API URL exists from prior CLI configuration, the stored value is used first. To force `ARDENT_API_URL`, run `ardent logout` in that environment first; this clears the stored API URL, token, selections, and cache. |

### Advanced polling controls

Most users should leave these unset. They exist for CI systems and operator-run automation that need a different wait budget or poll cadence while branch operations continue server-side.

| Variable                                | Default               | Applies to             | Notes                                                                                                                                                                                                         |
| --------------------------------------- | --------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ARDENT_BRANCH_CREATE_MAX_WAIT_MS`      | `600000` (10 minutes) | `ardent branch create` | Maximum time the CLI waits for the branch-create operation before exiting with an operation handle in the error message.                                                                                      |
| `ARDENT_BRANCH_CREATE_POLL_INTERVAL_MS` | adaptive polling      | `ardent branch create` | Forces a fixed poll interval in milliseconds. Use a positive value; negative and non-numeric values fail before any API request, while `0` creates a tight polling loop and should not be used.               |
| `ARDENT_BRANCH_DELETE_MAX_WAIT_MS`      | `600000` (10 minutes) | `ardent branch delete` | Maximum time the CLI waits for branch delete before exiting. The delete may still be running server-side.                                                                                                     |
| `ARDENT_BRANCH_DELETE_POLL_INTERVAL_MS` | `2000` (2 seconds)    | `ardent branch delete` | Fixed poll interval while waiting for branch delete. Use a positive value; `0` and non-numeric values fall back to the default, while negative values can create a tight polling loop and should not be used. |

<Warning>
  The two commands do not validate invalid poll-interval overrides the same way. For `ARDENT_BRANCH_CREATE_POLL_INTERVAL_MS`, negative and non-numeric values fail before any API request. For `ARDENT_BRANCH_DELETE_POLL_INTERVAL_MS`, negative values are accepted and can create a tight polling loop that hammers the API. Use a positive integer for both.
</Warning>

For GitHub Actions, store your token as a repository secret named `ARDENT_TOKEN`, then run commands normally:

```bash theme={null}
ARDENT_TOKEN="$ARDENT_TOKEN" ardent branch create pr-123 --print-url
```

## A complete first branch

```bash theme={null}
ardent login
ardent connector preflight postgresql 'postgresql://user:***@host:5432/mydb'
ardent connector create postgresql 'postgresql://user:***@host:5432/mydb' --name prod-db
ardent branch create my-feature --print-url
```

Preflight is intentionally first. It checks reachability, permissions, logical replication settings, and source readiness without creating a connector or storing credentials.

## Troubleshooting

| Symptom                                    | What to try                                                                                               |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| `Not authenticated`                        | Run `ardent login`, or set `ARDENT_TOKEN` in the current shell                                            |
| The wrong project or connector is selected | Run `ardent project list`, `ardent project switch <name>`, then `ardent connector switch <name>`          |
| A script needs the database URL only       | Use `ardent branch create <name> --print-url`                                                             |
| Preflight fails                            | Fix the specific check that failed, then re-run preflight before creating the connector                   |
| A branch URL is missing in CI              | Treat it as a hard failure. Re-run `ardent branch info --print-url` and stop the job if it prints nothing |