Faustine Docs
⌘K
Sign in
Apps menu

DocsAppsFaustine CLIHow-to

Call an operation from the CLI

View as MarkdownOpen in ClaudeOpen in ChatGPT

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

Find the operation

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

terminal
faustine ops contacts
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

terminal
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:

terminal
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:

terminal
faustine call nimbuscrm.contacts.list --limit 50 > contacts.json

Choose a connection

When an API has more than one connection that your credential can use, faustine connections lists them and marks the default:

terminal
faustine connections crm

To call through one of them, pass its name:

terminal
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.

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:

{
  "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.

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.

Next steps

Last updated November 11, 2026