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

# CLI

> Install and use the DBHost CLI.

DBHost CLI is published as `@dbhost-app/cli` for Pro and Business accounts.

## Install

Run the CLI directly with `npx`:

```bash theme={null}
npx @dbhost-app/cli@latest --help
```

Or install it globally:

```bash theme={null}
npm install -g @dbhost-app/cli
dbhost --help
```

DBHost CLI supports macOS and Linux with Node.js 18 or later.

## Authenticate

Create an API key from **Settings** in the dashboard, then log in:

```bash theme={null}
dbhost auth login --api-key dbh_your_api_key_here
```

The CLI stores the API key locally so you do not need to pass it on every command.

Paid plans support two API key scopes:

* `Selected databases` limits the key to only the databases you choose
* `Full account access` can create and manage every database in your account

`Selected databases` is the recommended default. A `Full account access` key is required for database creation, collaborator/member/invitation administration, and webhook administration.

Selected-database keys only list the databases they can access. If you use a database-specific command against an out-of-scope database, the API responds as if the resource were missing.

{/* cli-meta:docs-cli-env:start */}

If you prefer environment variables:

```bash theme={null}
export DBHOST_API_KEY=dbh_your_api_key_here
export DBHOST_API_URL=https://dbhost.app/api/v1
```

<Warning>
  Local tests and smoke runs for mutating commands must set `DBHOST_API_URL` to
  an explicit local test server. They fail closed rather than using the
  production default. This rule does not authorize a production CLI mutation.
</Warning>

## Common commands

List databases:

```bash theme={null}
dbhost databases list
```

Use the `id` column from the list output with `dbhost databases get <id>`.

Create a database:

```bash theme={null}
dbhost databases create analytics-v2 --display-name "Analytics V2"
```

Or pass the display name as the second argument:

```bash theme={null}
dbhost databases create analytics-v2 "Analytics V2"
```

Trigger a backup:

```bash theme={null}
dbhost backups trigger <database-id>
```

Download a backup file:

```bash theme={null}
dbhost backups download <database-id> 20260326_222551.sql.gz
```

Delete a backup file:

```bash theme={null}
dbhost backups delete <database-id> 20260326_222551.sql.gz --yes
```

Reset a database password:

```bash theme={null}
dbhost databases reset-password <database-id>
```

Repair ownership after a pg\_dump restore (fixes `permission denied` from the app role):

```bash theme={null}
dbhost databases repair-ownership <database-id>
```

Wait for an asynchronous operation:

```bash theme={null}
dbhost operations wait <operation-id>
```

Manage lifecycle and environment metadata:

```bash theme={null}
dbhost databases stop <database-id>
dbhost databases environment <database-id> staging
```

Use `dbhost backups list <database-id>` to discover the `filename` value before you download or delete a specific backup. Downloads save to `./<filename>` by default; pass `--output` to write the file somewhere else.

## JSON output

Add `--json` to any command for machine-readable output:

```bash theme={null}
dbhost databases list --json
dbhost backups list <database-id> --json
```

## Supported commands

* `dbhost auth login [--api-key KEY] [--base-url URL]`
* `dbhost auth logout`
* `dbhost databases list [--json]`
* `dbhost databases get <id> [--json]`
* `dbhost databases create <name> [display-name] [--display-name "My App"] [--json]`
* `dbhost databases start|stop|restart <id> [--json]`
* `dbhost databases environment <id> <production|staging|development|other|none> [--json]`
* `dbhost databases reset-password <id> [--json]`
* `dbhost databases repair-ownership <id> [--json]`
* `dbhost backups list <database-id> [--json]`
* `dbhost backups trigger <database-id> [--no-wait] [--json]`
* `dbhost backups download <database-id> <filename> [--output PATH] [--json]`
* `dbhost backups delete <database-id> <filename> [--yes] [--json]`
* `dbhost operations get|wait <operation-id> [--timeout SECONDS] [--json]`
* `dbhost network list <database-id> [--json]`
* `dbhost network add <database-id> <cidr> [label] [--json]`
* `dbhost network remove <database-id> <entry-id> [--json]`
* `dbhost members list <database-id> [--json]`
* `dbhost members add <database-id> <email> <admin|developer|viewer> [--json]`
* `dbhost members update <database-id> <membership-id> <role> [--json]`
* `dbhost members remove <database-id> <membership-id> [--json]`
* `dbhost invitations list <database-id> [--json]`
* `dbhost invitations resend|revoke <database-id> <invitation-id> [--json]`
* `dbhost webhooks list [--json]`
* `dbhost webhooks create <https-url> [database-id] [--json]`
* `dbhost webhooks rotate|disable <webhook-id> [--json]`