faustine CLI | Faustine Docs

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

terminal

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`	Signs in to a gateway and saves it.
`logout`	Removes a saved gateway.
`gateways`	Lists the saved gateways.
`use`	Changes the current gateway.
`whoami`	Shows the gateway, the credential and what it can use.
`ops`	Lists or searches the operations.
`help`	Describes an operation or a command.
`call`	Calls an operation.
`connections`	Lists the connections of an API.
`docs`	Opens the gateway's docs page.
`skill`	Prints the gateway's skill file.
`openapi`	Prints the gateway's OpenAPI document.

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

terminal

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.

terminal

faustine login nimbus/crm --alias crm-prod

logout

terminal

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.

terminal

faustine logout crm-prod

gateways

terminal

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

terminal

faustine use [alias]

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

terminal

faustine use crm-prod

whoami

terminal

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.

terminal

faustine whoami --json

ops

terminal

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.

terminal

faustine ops contacts

help

terminal

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.

terminal

faustine help crm.contacts.create

call

terminal

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

terminal

faustine call crm.contacts.create --name "Dana Whitfield" --email [email protected]

connections

terminal

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.

terminal

faustine connections crm

docs

terminal

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.

terminal

faustine docs --no-open

skill

terminal

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.

terminal

faustine skill --out SKILL.md

openapi

terminal

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.

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

terminal

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:

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

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: install the package and sign in to a gateway.
Call an operation from the CLI: examples of each kind of input.
Gateway HTTP: the REST interface the CLI calls and the codes it returns.