# Call an operation from the CLI

`faustine call` runs one operation of a gateway and prints what your API answered. The operation's input fields are the command's options, so you find the operation and read its inputs first.

The operation keys on this page are examples from a Nimbus CRM gateway. Yours come from `faustine ops`.

## Before you begin

- The CLI is installed and signed in to a gateway. See [Install the CLI and sign in](https://docs.faustine.ai/apps/cli-install/).

## Find the operation

List the operations, or pass one search term to match their keys, summaries and descriptions:

```bash
faustine ops contacts
```

```text
key                  flags          summary
-------------------  -------------  ------------------------
nimbuscrm.contacts.create  write          Create a contact
nimbuscrm.contacts.delete  write,confirm  Delete a contact
nimbuscrm.contacts.list    read-only      List and search contacts
```

The `flags` column says whether the operation reads or writes. `confirm` marks an operation that requires confirmation.

## Read its inputs

```bash
faustine help nimbuscrm.contacts.list
```

The command prints the operation's description, a table of its input options with their type and whether they are required, its output fields, and an example `faustine call` line.

## Call it

Pass each input field as an option:

```bash
faustine call nimbuscrm.contacts.list --limit 2 --q whitfield
```

The CLI converts each value to the type the operation declares. `--limit 2` is sent as a number.

| Input | How to pass it |
| --- | --- |
| Text or number | `--name "Dana Whitfield"`, `--limit 2`, or `--limit=2` |
| True or false | `--archived` for true, `--no-archived` for false |
| List | Values separated by commas: `--tags lead,priority` |
| Nested object | One option for each field, joined with a dot: `--address.city Lisbon` |
| Empty value | `null`, where the operation allows it |
| The whole input as JSON | `--json '{"limit":2}'`. Options you also pass replace the fields of the JSON. |

An option that is not a field of the operation fails with exit code 1 and the list of valid fields.

On a terminal, a result that is a list of objects prints as a table. To get JSON, add a bare `--json`, or send the output to a pipe or a file:

```bash
faustine call nimbuscrm.contacts.list --limit 50 > contacts.json
```

## Choose a connection

When an API has more than one [connection](https://docs.faustine.ai/apis/connections/) that your credential can use, `faustine connections` lists them and marks the default:

```bash
faustine connections crm
```

To call through one of them, pass its name:

```bash
faustine call nimbuscrm.contacts.list --connection Staging
```

`--all` sends the call through every connection and returns one result for each. The gateway has to allow it. See [Routing: fixed, dynamic and fan-out](https://docs.faustine.ai/agent-gateway/routing/).

## Read an error

A failed call prints the error on standard error and exits with a code other than 0. In a pipe, or with `--json`, the error is a JSON object:

```json
{
  "error": {
    "code": "read_only",
    "message": "Denied (read_only): This key is read-only; \"nimbuscrm.contacts.delete\" modifies data",
    "requestId": "<REQUEST_ID>"
  }
}
```

`requestId` identifies the call in the gateway's [logs](https://docs.faustine.ai/agent-gateway/logs/).

| Exit code | Meaning | Examples of `code` |
| --- | --- | --- |
| 1 | The command was wrong. | `usage` |
| 2 | No credential, or the gateway rejected it. | `no_gateway`, `unauthorized`, `session_expired` |
| 3 | The gateway refused the call. | `scope`, `read_only`, `requires_confirmation`, `rate_limit`, `unknown_operation` |
| 4 | Your API or the gateway failed. | `upstream_error`, `gateway_paused` |
| 5 | The CLI could not reach the gateway. | `network` |

A call to an operation that requires confirmation is refused with `requires_confirmation` unless the credential is allowed to run it. See [Confirmation](https://docs.faustine.ai/agent-gateway/confirmation/).

## Next steps

- [faustine CLI](https://docs.faustine.ai/reference/faustine-cli/): every option of `call` and the full list of exit codes.
- [Use the CLI from a coding agent](https://docs.faustine.ai/apps/cli-coding-agents/): let an agent find and call operations.
- [Create an API key](https://docs.faustine.ai/agent-gateway/api-keys/): a key with its own scope and limits for a script.