# Install the CLI and sign in

Install the Faustine CLI and sign in to one of your gateways. At the end, `faustine ops` lists the operations of the gateway in your terminal.

## Prerequisites

- Node.js 22 or later.
- A published gateway. See [Publish your API as an MCP server](https://docs.faustine.ai/agent-gateway/publish-your-api-as-an-mcp-server/).
- A credential for it: a [gateway user](https://docs.faustine.ai/agent-gateway/gateway-users/) to sign in as a person, or an [API key](https://docs.faustine.ai/agent-gateway/api-keys/) for a script.

## 1. Install the package

**npm**

```bash
npm install -g @faustine-ai/cli
```

**pnpm**

```bash
pnpm add -g @faustine-ai/cli
```

**yarn**

```bash
yarn global add @faustine-ai/cli
```

**bun**

```bash
bun add -g @faustine-ai/cli
```

Check the installation:

```bash
faustine --version
```

The command prints the version, such as `0.2.2`.

## 2. Find your gateway's name

`faustine login` takes the gateway as `<workspace>/<gateway>`: your workspace's slug and the gateway's slug. In the portal, go to [**Faustine CLI**](https://auth.faustine.ai/go?to=%2Fapps%2Ffaustine-cli) and choose your gateway in the **Sign in** section. The commands on that page then carry your gateway's name.

A gateway on its own domain is written `<domain>/<gateway>`, such as `gateway.nimbuscrm.example/crm`. See [Use a custom domain](https://docs.faustine.ai/agent-gateway/custom-domain/).

## 3. Sign in

**Gateway user**

```bash
faustine login <workspace>/<gateway>
```

The CLI opens the gateway's sign-in page in your browser. Enter the username and password of your gateway user. The CLI waits up to 5 minutes for you to finish.

On a machine without a browser, such as a server you reach over SSH, add `--manual`. The CLI prints a URL. Open it on any device, sign in, and paste the address the browser ends on back into the terminal.

```bash
faustine login <workspace>/<gateway> --manual
```

**API key**

Replace `fik_…` with the key you copied when you created it.

```bash
faustine login <workspace>/<gateway> --api-key fik_…
```

The CLI checks the credential against the gateway, saves it under an alias and prints a line such as `Logged in to Nimbus CRM as alias "crm" (oauth).` The alias is the gateway's slug.

## 4. List the operations

```bash
faustine whoami
```

`whoami` prints the gateway, the kind of credential, and the number of operations the credential can use for each API.

```bash
faustine ops
```

> **Checkpoint:** The terminal shows a table with one row for each operation: its key, `read-only` or `write`, and a summary. The last line gives the count.

## Sign in without saving a credential

In CI, set the gateway and the key as environment variables. The CLI then does not use the credentials file. `FAUSTINE_GATEWAY` is the gateway's MCP URL. The **With an API key** card of the **Faustine CLI** page shows these lines with your gateway's URL.

```bash
export FAUSTINE_GATEWAY=https://gateway.faustine.ai/<workspace>/<gateway>/mcp
export FAUSTINE_API_KEY=fik_…
faustine ops
```

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| `No gateway configured. Run faustine login <tenant/gateway> or set FAUSTINE_GATEWAY (and FAUSTINE_API_KEY).` | No gateway is saved and the variables are not set. | Sign in, or set both variables. |
| `Unauthorized for …. Check your credential or run faustine login.` | The key was revoked or mistyped, or the user's session was ended. | Sign in again with a valid credential. |
| `Timed out waiting for the browser login` | The browser sign-in was not finished within 5 minutes. | Run `faustine login` again, or use `--manual`. |
| `target must be tenant/gateway …` | The gateway's name is not `<workspace>/<gateway>`, `<domain>/<gateway>` or a URL. | Copy the command from the **Faustine CLI** page of the portal. |

## Next steps

- [Call an operation from the CLI](https://docs.faustine.ai/apps/cli-call-an-operation/): pass inputs and read the result.
- [Use the CLI from a coding agent](https://docs.faustine.ai/apps/cli-coding-agents/): let an agent run `faustine` for you.
- [faustine CLI](https://docs.faustine.ai/reference/faustine-cli/): every command and option.