# faustine CLI

`faustine` is the command installed by `@faustine-ai/cli`. It signs in to a gateway, lists its operations and calls them. This page describes version 0.2.2.

## Usage

```bash
faustine [global options] <command> [arguments] [options]
```

Global options work before or after the command. `faustine --help` lists the commands, `faustine <command> --help` describes one, and `faustine --version` prints the version.

| Command | What it does |
| --- | --- |
| [`login`](#login) | Signs in to a gateway and saves it. |
| [`logout`](#logout) | Removes a saved gateway. |
| [`gateways`](#gateways) | Lists the saved gateways. |
| [`use`](#use) | Changes the current gateway. |
| [`whoami`](#whoami) | Shows the gateway, the credential and what it can use. |
| [`ops`](#ops) | Lists or searches the operations. |
| [`help`](#help) | Describes an operation or a command. |
| [`call`](#call) | Calls an operation. |
| [`connections`](#connections) | Lists the connections of an API. |
| [`docs`](#docs) | Opens the gateway's docs page. |
| [`skill`](#skill) | Prints the gateway's skill file. |
| [`openapi`](#openapi) | Prints the gateway's OpenAPI document. |

Operation keys such as `crm.contacts.list` are examples from a Nimbus CRM gateway.

## login

```bash
faustine login [target] [options]
```

Signs in to a gateway, saves the gateway and the credential under an alias and makes the gateway the current one. Without `--api-key`, it signs in as a gateway user through the browser.

| Argument | Description |
| --- | --- |
| `target` | The gateway, in one of three forms: `<workspace>/<gateway>`, `<domain>/<gateway>` for a gateway on its own domain, or the gateway's full MCP URL. Without it, on a terminal, the CLI asks for the two parts. |

| Option | Description |
| --- | --- |
| `-a, --alias <name>` | The alias to save the gateway under. The default is the gateway's slug. |
| `-k, --api-key <key>` | Signs in with an API key instead of the browser. |
| `-b, --browser` | Opens the browser to sign in as a gateway user. This is the default on a terminal. |
| `-m, --manual` | Prints the sign-in URL instead of opening a browser. Paste back the address the browser ends on, or the code in it. When the input is not a terminal, the CLI reads it from standard input. |
| `--host <host>` | The host that `<workspace>/<gateway>` is resolved against. The default is `FAUSTINE_GATEWAY_HOST`, then `gateway.faustine.ai`. |

The CLI uses the manual flow without `--manual` when `FAUSTINE_NO_BROWSER` is `1` or its output is not a terminal. The browser flow waits 5 minutes.

```bash
faustine login nimbus/crm --alias crm-prod
```

## logout

```bash
faustine logout [alias]
```

Removes a saved gateway and its credential. Without `alias`, it removes the current gateway. For a gateway user, the CLI also asks the gateway to end the session.

```bash
faustine logout crm-prod
```

## gateways

```bash
faustine gateways
```

Lists the saved gateways with their alias, kind of credential (`key` or `oauth`), MCP URL and, for a gateway user, when the access token expires. `*` marks the current gateway.

## use

```bash
faustine use [alias]
```

Makes a saved gateway the current one. Without `alias`, on a terminal, the CLI shows the saved gateways to choose from.

```bash
faustine use crm-prod
```

## whoami

```bash
faustine whoami
```

Prints the gateway's name and MCP URL, the alias, the kind of credential (`key` or `user`), the number of operations the credential can use, and the APIs of the gateway with the count for each.

```bash
faustine whoami --json
```

## ops

```bash
faustine ops [query]
```

Lists the operations the credential can use, sorted by key, with their flags and summary. The flags are `read-only` or `write`, `confirm` for an operation that requires confirmation, and `composite` for a recipe.

| Argument | Description |
| --- | --- |
| `query` | Words to search for. An operation matches when its key, summary, description or path contains every word. |

```bash
faustine ops contacts
```

## help

```bash
faustine help [name]
```

Describes an operation: its summary and description, its flags, its HTTP method and path, a table of input options, its output fields and an example `faustine call` line. With `--json`, it prints the operation as JSON, with its input and output schemas.

| Argument | Description |
| --- | --- |
| `name` | An operation key, or the name of a command. With a command, it prints that command's help. Without it, it prints the CLI's help. |

```bash
faustine help crm.contacts.create
```

## call

```bash
faustine call <operation> [--field value ...] [options]
```

Calls an operation and prints the body your API returned. Every option that is not in the table below is an input field of the operation.

| Argument | Description |
| --- | --- |
| `operation` | The operation's key, as `faustine ops` prints it. |
| `--field value` | An input field. `--field=value` also works. The value is converted to the type the operation declares: numbers, `true` and `false`, lists separated by commas, and JSON for objects and lists. `--field` alone is `true` and `--no-field` is `false`. `null` is accepted where the operation allows it. A nested field is written `--parent.child value`. |
| JSON object | The whole input as one argument, such as `'{"limit":2}'`. Same as `--json` with a value. |

| Option | Description |
| --- | --- |
| `-j, --json [input]` | With a value, the input as a JSON object. Fields passed as options replace the fields of the JSON. Without a value, forces JSON output. |
| `-c, --connection <name>` | The connection to call through. `faustine connections` lists the names. |
| `--all` | Calls through every connection of the operation's API and returns one result for each. The API's routing in the gateway has to be fan-out. See [Routing: fixed, dynamic and fan-out](https://docs.faustine.ai/agent-gateway/routing/). |
| `-s, --select <fields>` | The output fields to return, separated by commas. Nested fields use a dot. Available on operations whose `help` says they support `$select`. |
| `--raw` | Prints the gateway's response as it is, with the status of your API's response around the body. |

An option that is not an input field of the operation fails with exit code 1, and the error lists the valid fields.

```bash
faustine call crm.contacts.create --name "Dana Whitfield" --email dana@nimbuscrm.example
```

## connections

```bash
faustine connections [api]
```

Lists the connections the credential can choose from for an API, and which one is the default. An API with one connection has nothing to list, and the command fails with the code `unsupported`.

| Argument | Description |
| --- | --- |
| `api` | The API's namespace, the first part of its operation keys. Required when more than one API of the gateway has a choice of connections. |

```bash
faustine connections crm
```

## docs

```bash
faustine docs [options]
```

Opens the gateway's docs page in the browser and prints its URL with the URLs of the OpenAPI document and the skill file.

| Option | Description |
| --- | --- |
| `--no-open` | Prints the URLs without opening the browser. The CLI also does not open it when its output is not a terminal. |

```bash
faustine docs --no-open
```

## skill

```bash
faustine skill [options]
```

Prints the gateway's skill file, a Markdown file with instructions for an agent.

| Option | Description |
| --- | --- |
| `-o, --out <file>` | Writes the file to `file` instead of printing it. |

```bash
faustine skill --out SKILL.md
```

## openapi

```bash
faustine openapi [options]
```

Prints the gateway's OpenAPI document, which describes the operations the credential can use over the gateway's REST interface. See [Gateway HTTP](https://docs.faustine.ai/reference/gateway-http/).

| Option | Description |
| --- | --- |
| `-o, --out <file>` | Writes the document to `file` instead of printing it. |

```bash
faustine openapi --out openapi.json
```

## Global options

| Option | Description |
| --- | --- |
| `-g, --gateway <url\|alias>` | The gateway for this command: an MCP URL or a saved alias. |
| `-k, --api-key <key>` | The API key for this command. It is used instead of the saved credential and is not saved. |
| `--json` | Prints JSON. This is the default when the output is not a terminal. |
| `--pretty` | Prints tables and colors even when the output is not a terminal. |
| `-q, --quiet` | Leaves out the informational lines on standard error. |
| `-h, --help` | Prints the help of the CLI or of the command. |
| `-v, --version` | Prints the version. |

A command chooses its gateway from `--gateway`, then `FAUSTINE_GATEWAY`, then the current saved gateway.

## Environment variables

| Variable | Description |
| --- | --- |
| `FAUSTINE_GATEWAY` | The gateway to use: an MCP URL or a saved alias. |
| `FAUSTINE_API_KEY` | The API key to use. It replaces the saved credential of the gateway. |
| `FAUSTINE_GATEWAY_HOST` | The host that `faustine login <workspace>/<gateway>` is resolved against. The default is `gateway.faustine.ai`. |
| `FAUSTINE_CONFIG_DIR` | The directory of `credentials.json`. The default is `$XDG_CONFIG_HOME/faustine` when `XDG_CONFIG_HOME` is set, and `~/.config/faustine` otherwise. |
| `FAUSTINE_NO_BROWSER` | `1` makes `faustine login` use the manual flow. |
| `NO_COLOR` | Any value turns off colors. |

## Credentials file

`faustine login` writes `credentials.json` in the configuration directory, readable by your user only. It holds the current alias and, for each alias, the gateway's MCP URL and its credential: the API key, or the access and refresh tokens of a gateway user.

## Errors

A failed command prints the error on standard error. On a terminal it is one line, `error (<code>): <message>`. With `--json`, or when the output is not a terminal, it is a JSON object:

```json
{
  "error": {
    "code": "scope",
    "message": "<MESSAGE>",
    "requestId": "<REQUEST_ID>"
  }
}
```

| Field | Description |
| --- | --- |
| `code` | A stable identifier of the failure. |
| `message` | A sentence for a person. |
| `requestId` | Present when the gateway refused or failed a call. It identifies the call in the gateway's logs. |
| `validFields` | Present when `call` received an option that is not an input field. The list of valid fields. |

The CLI produces these codes itself:

| Code | Meaning |
| --- | --- |
| `usage` | Wrong arguments, an unknown command, an unknown alias or an unknown input field. |
| `no_gateway` | No gateway is saved and `FAUSTINE_GATEWAY` is not set. |
| `no_credential` | The gateway is known and there is no credential for it. |
| `unauthorized` | The gateway rejected the credential. |
| `session_expired` | The gateway user's session expired or was ended. Sign in again. |
| `oauth_timeout` | The browser sign-in was not finished in 5 minutes. |
| `unknown_operation` | The operation is not one the credential can use. |
| `unsupported` | `connections` was asked about an API with one connection. |
| `forbidden` | The gateway refused to serve its OpenAPI document or skill file to the credential. |
| `gateway_error` | The gateway answered a request for its OpenAPI document or skill file with an error. |
| `network` | The gateway could not be reached. |

On a call, `code` is the code the gateway returned, such as `scope`, `read_only`, `requires_confirmation`, `rate_limit`, `quota` or `upstream_error`. See [Gateway HTTP](https://docs.faustine.ai/reference/gateway-http/).

## Exit codes

| Code | Meaning | Error codes |
| --- | --- | --- |
| `0` | Success. | |
| `1` | The command was wrong. | `usage` |
| `2` | No credential, or the gateway rejected it. A key or user that has expired or is not valid yet also ends here, as `unauthorized`. | `no_gateway`, `no_credential`, `unauthorized`, `session_expired`, `oauth_timeout` |
| `3` | The gateway refused the call. | `scope`, `read_only`, `requires_confirmation`, `rate_limit`, `quota`, `concurrency`, `ip_not_allowed`, `ip_blocked`, `channel`, `unknown_operation`, `forbidden`, `unsupported` |
| `4` | Your API or the gateway failed. | `upstream_error`, `gateway_paused`, `gateway_error` and every other code the gateway returns |
| `5` | The CLI could not reach the gateway. | `network` |

## Next steps

- [Install the CLI and sign in](https://docs.faustine.ai/apps/cli-install/): install the package and sign in to a gateway.
- [Call an operation from the CLI](https://docs.faustine.ai/apps/cli-call-an-operation/): examples of each kind of input.
- [Gateway HTTP](https://docs.faustine.ai/reference/gateway-http/): the REST interface the CLI calls and the codes it returns.