# CLI Install and Setup

The DBGorilla CLI is how you set up collectors and wire AI tools into DBGorilla. Install it once,
sign in once, and every other page that needs it can assume both are done.

## Install

The binary is `dbgorilla`. Homebrew also installs `dbg` as an alias for it.

### Homebrew

```sh
brew install dbgorilla/tap/dbgorilla
```

Use the full `dbgorilla/tap/dbgorilla` name. Tab completion for bash, zsh and fish is set up for
you.

### Go

```sh
go install github.com/dbgorilla/dbgorilla-cli/cmd/dbgorilla@latest
```

A Go install gives you `dbgorilla` only. If you want the shorter `dbg`, create the symlink
yourself:

```sh
ln -s "$(which dbgorilla)" /usr/local/bin/dbg
```

### Manual download

Binaries are on the [releases page](https://github.com/dbgorilla/dbgorilla-cli/releases).

| File | Platform |
|---|---|
| `dbg-darwin-arm64` | macOS, Apple silicon |
| `dbg-darwin-amd64` | macOS, Intel |
| `dbg-linux-arm64` | Linux, arm64 |
| `dbg-linux-amd64` | Linux, x86-64 |

There is no Windows build. Rename the file you download to `dbgorilla` and put it on your `PATH`.

### Verify a download

Every release binary carries build provenance, so you can confirm where it came from before you
run it. This needs the [GitHub CLI](https://cli.github.com):

```sh
gh attestation verify dbg-darwin-arm64 \
  --repo dbgorilla/dbgorilla-cli \
  --signer-workflow dbgorilla/dbgorilla-cli/.github/workflows/release.yml
```

An exit code of `0` confirms the file was built by that repository's release workflow. Naming the
workflow matters: `--repo` on its own accepts anything built anywhere in the repository, and the
release workflow is the only thing that should be producing these binaries.

:::note[About the `.sig` files]

Each binary also ships with a detached `.sig`. Keyless signing puts the proof of who signed into a
short-lived certificate rather than a long-lived key, and a `.sig` on its own does not carry that
certificate, so use the provenance check above, which verifies end to end today.
:::

For Go and manual installs, set up completion separately:

```sh
source <(dbgorilla completion zsh)   # this shell only
dbgorilla completion --help          # bash, zsh, fish, powershell
```

## Sign in

```sh
dbgorilla login
```

On DBGorilla SaaS that is the whole command. The CLI talks to `app.dbgorilla.com` unless you tell
it otherwise.

:::note[Self-hosted and on-premise deployments]

If DBGorilla runs on your own infrastructure, give the CLI its address the first time you sign in:

```sh
dbgorilla login --api-url https://dbgorilla.your-company.example
```

That is the only time you type it. The address is saved to `~/.config/dbgorilla/cli.toml`, and
every command after this one reads it from there. Everything else on this page works the same way
for you as it does on SaaS.
:::

The CLI picks the sign-in mode for you: it asks your deployment whether single sign-on is enabled.
If it is, you get the browser device flow, where the CLI prints a code you approve in a browser.
If it is not, you get a username and password prompt. Force one with `--mode sso` or
`--mode password`. In password mode you can pass `--account` and `--tenant` instead of being
prompted.

Check it worked:

```sh
dbgorilla whoami          # your email and organization
dbgorilla whoami --json   # the same, as JSON
```

## Check your setup

```sh
dbgorilla doctor
```

It checks your API URL and where it came from, your auth token, that an MCP key exists, and then
one check per detected editor. It exits 0 only if everything passed.

```text
Checking DBGorilla setup...

  [ OK ] API URL            https://app.dbgorilla.com  (source: default)
  [ OK ] Auth + API         you@example.com  (org: ...)
  [ OK ] MCP API key        exists
  [ OK ] MCP: Claude Code   registered (`claude mcp list`)
  [ OK ] MCP: Cursor        entry present in ~/.cursor/mcp.json
  [FAIL] MCP: VS Code       no config at ./.vscode/mcp.json -- run: dbgorilla setup-ide --client vscode
  [ OK ] MCP: Gemini CLI    entry present in ~/.gemini/settings.json
```

:::caution[`doctor` exits 1 in two situations that are not faults]

If VS Code is installed, `doctor` looks for `.vscode/mcp.json` in the directory you ran it from. In
any directory that is not a VS Code project you set up, that check fails and `doctor` exits 1 even
though your setup is fine.

It also reports a failure when it finds no supported editors at all, which is the expected state if
you use the CLI for collectors and never wire up an editor.

Read the individual lines rather than the exit code.
:::

## Configuration

Two settings persist: `api-url` and `insecure`.

```sh
dbgorilla config get api-url    # the value, and where it came from
dbgorilla config set api-url https://dbgorilla.your-company.example
dbgorilla config unset api-url
```

A setting can come from five places. The first one wins:

1. `--api-url` on the command line
2. the `DBGORILLA_API_URL` environment variable
3. your config file: `~/.config/dbgorilla/cli.toml`, or `$XDG_CONFIG_HOME/dbgorilla/cli.toml`
4. a system-wide file your IT team deploys: `/Library/Application Support/dbgorilla/cli.toml` on
   macOS, `/etc/dbgorilla/cli.toml` on Linux
5. `app.dbgorilla.com`, the built-in default

`dbgorilla config unset api-url` therefore returns you to SaaS rather than leaving the CLI with
nowhere to talk to.

`dbgorilla config get` tells you which layer won, which is the fastest way to find out why a
command is talking to the wrong deployment.

:::caution[`--insecure` is sticky]

`-k` / `--insecure` turns off TLS certificate checking. Passing it to `dbgorilla login` writes it
to your config file, and it then applies to every later command with no flag and no warning. Only
Clear it with `dbgorilla config unset insecure`, or override a single command with
`--insecure=false`. One catch: the user and system-wide settings are combined rather than
overridden, so if your IT team set `insecure` in the system-wide file, clearing your own config
does not switch it off. Only `--insecure=false` on the command line does.
:::

## Updating

```sh
dbgorilla upgrade
```

On a Homebrew install this runs `brew upgrade` for you. On any other install it does not update
anything: it prints instructions and you run them yourself. Download the current binary from the
[releases page](https://github.com/dbgorilla/dbgorilla-cli/releases) and replace the file. The CLI
does not replace its own binary.

## Signing out

```sh
dbgorilla logout
```