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 when you are building your own automation or platform integration.
Install
npm install -g ardent-cli
ardent --version
ardent --help
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:
- A project groups related connectors and branches.
- A connector points to one Postgres source server.
- 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:
ardent project switch my-project
ardent connector switch prod-db
ardent branch switch my-feature
Human output and automation output
Most commands print friendly terminal output by default. Branch commands also support automation-friendly output:
ardent branch create pr-123 --print-url
ardent branch info my-feature --format json
--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. |
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.
ARDENT_TOKEN, then run commands normally:
ARDENT_TOKEN="$ARDENT_TOKEN" ardent branch create pr-123 --print-url
A complete first branch
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
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 |
