# Use the CLI from a coding agent

A coding agent that can run shell commands can use a gateway through `faustine`, with no MCP server to configure. The agent lists the operations, reads the inputs of the one it needs and calls it, the same three commands a person runs.

To connect an agent over MCP instead, see [Connect clients](https://docs.faustine.ai/agent-gateway/connect-clients/).

## Before you begin

- The CLI is installed on the machine where the agent runs. See [Install the CLI and sign in](https://docs.faustine.ai/apps/cli-install/).
- An API key for the gateway. Create one for the agent, with the scope it needs, so you can revoke it without affecting anyone else. See [Create an API key](https://docs.faustine.ai/agent-gateway/api-keys/).

## Give the agent the gateway and the key

Set two environment variables in the shell the agent starts from. `FAUSTINE_GATEWAY` is the gateway's MCP URL and `FAUSTINE_API_KEY` is the key.

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

With both set, `faustine` does not use the credentials file, so the agent works the same on your machine and in CI.

## Tell the agent what to run

The agent needs three commands. Put them in its instructions, such as the `CLAUDE.md` or `AGENTS.md` of your repository:

```text
Use the `faustine` command to work with Nimbus CRM.
- `faustine ops [query]` lists the operations.
- `faustine help <operation>` shows the inputs and an example.
- `faustine call <operation> --field value` runs it.
Run `faustine help <operation>` before the first call to an operation.
```

`faustine --help` prints the same sequence, so an agent that explores the command finds it without instructions.

## Run it from Claude Code

Allow the `faustine` command and give the task. This example runs Claude Code once, without a session:

```bash
claude -p --allowedTools "Bash(faustine *)" "List the contacts added this week and create a follow-up deal for each one"
```

For Claude Code over MCP, see [Connect Claude Code](https://docs.faustine.ai/technologies/claude-code/).

## Give the agent the gateway's skill file

Each gateway publishes a skill file that describes the system behind it and how to discover its operations. `faustine skill` downloads it:

```bash
mkdir -p .claude/skills/nimbus-crm
faustine skill --out .claude/skills/nimbus-crm/SKILL.md
```

`.claude/skills/<name>/SKILL.md` is where Claude Code loads skills from a repository. For another agent, save the file where that agent reads its instructions.

## What the agent gets back

| Behavior | Detail |
| --- | --- |
| Output | JSON whenever the output is not a terminal, which is the case for an agent. |
| Errors | A JSON object on standard error: `{"error":{"code":"…","message":"…"}}`. `code` is stable. |
| Exit codes | `0` success, `1` wrong command, `2` credential, `3` refused by the gateway, `4` your API or the gateway failed, `5` network. |
| Prompts | None when the input is not a terminal. |
| Status lines | Informational lines go to standard error. `--quiet` removes them. |

An unknown input field fails with exit code 1 and the list of valid fields, which the agent uses to correct the call.

The gateway applies the key's settings to every call. A read-only key gets `read_only` on a write, and an operation that requires confirmation gets `requires_confirmation` unless the key is allowed to run it. See [Confirmation](https://docs.faustine.ai/agent-gateway/confirmation/).

## Next steps

- [Call an operation from the CLI](https://docs.faustine.ai/apps/cli-call-an-operation/): how inputs are passed and what each error means.
- [faustine CLI](https://docs.faustine.ai/reference/faustine-cli/): every command, environment variable and exit code.
- [Connect Claude Code](https://docs.faustine.ai/technologies/claude-code/): use the gateway over MCP instead of the shell.