CLI reference - Ardent

The Ardent CLI connects your Postgres database to Ardent, creates isolated branches of it, and gives you their connection URLs. Use the CLI at a terminal. Use the API when you’re building your own integration.

Install

npm install -g ardent-cli

Needs Node.js 18 or newer. Check it worked:

ardent --version

Every command explains itself with --help:

ardent branch create --help

The commands

Group	What it manages
`ardent login`, `ardent logout`, `ardent status`	Your session
`ardent project ...`	Projects — the top-level grouping
`ardent connector ...`	Source databases Ardent can branch
`ardent branch ...`	Isolated database branches and their URLs
`ardent settings ...`	Defaults for new branches
`ardent invite ...`, `ardent org ...`	Your team

How the CLI knows what you mean

The CLI remembers three things: your current project, connector, and branch. Commands act on the current one unless you say otherwise. After login, Ardent picks your project and connector for you if you only have one of each. If you have more, pick them yourself:

ardent project switch my-project
ardent connector switch prod-db
ardent branch switch my-feature

In CI, always switch project and connector explicitly. Scripts shouldn’t depend on someone’s saved defaults.

Output for scripts

Two flags cover most automation:

ardent branch create pr-123 --print-url    # prints only the connection URL
ardent branch info my-feature --format json # prints a stable JSON object

The JSON format, error codes, and exit codes are documented on Configuration & automation.

Environment variables

Variable	What it does
`ARDENT_TOKEN`	Authenticate without `ardent login`. When set, it always wins — even if this machine has a stored login.
`ARDENT_API_URL`	Point at a different API endpoint. When set, it always wins. Default: `https://api.tryardent.com`.

That’s all most people need. Timeout and polling knobs for CI live on Configuration & automation. For GitHub Actions, store your token as a secret named ARDENT_TOKEN and run commands normally:

env:
  ARDENT_TOKEN: ${{ secrets.ARDENT_TOKEN }}

steps:
  - run: npm install -g ardent-cli
  - run: ardent project switch my-project
  - run: ardent connector switch prod-db
  - run: echo "DATABASE_URL=$(ardent branch create pr-${{ github.run_id }} --print-url)" >> "$GITHUB_ENV"

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

Preflight comes first on purpose. It checks that your database is ready — without creating anything or storing credentials.

Troubleshooting

Symptom	What to try
`Not authenticated`	Run `ardent login`, or set `ARDENT_TOKEN`
Wrong project or connector selected	`ardent project list`, then `ardent project switch <name>` and `ardent connector switch <name>`
A script needs only the database URL	`ardent branch create <name> --print-url`
Preflight fails	Fix the check it names, then run preflight again
A branch URL is missing in CI	Treat it as a failure and stop the job. Re-run `ardent branch info --print-url` to check

​Install

​The commands

​How the CLI knows what you mean

​Output for scripts

​Environment variables

​A complete first branch

​Troubleshooting