CLI reference

Every finch command, grouped by what you do with it. All commands are non-interactive except the one-time browser approval in finch login. Run finch help for the flag-level reference, or finch <command> -h for a single command's flags.

Driving finch with an agent? finch guide prints a complete, self-contained operating manual. Point an agent at it once and it can run the whole loop: serve, test, grant and revoke access.

Setup

Command	What it does
`finch login [--hub URL] [--token -]`	Log in. With no token it opens the browser to approve a short code. With `--token -` it reads a token minted by `finch token` from stdin (or set `FINCH_CLI_TOKEN`), no browser. Passing the token as an argument still works but warns: it lands in the process table and shell history.
`finch add <app_path> --service <url>`	Enroll a service and append an ingress rule to `finch.yml`. The `app_path` becomes the URL segment: `<slug>.finchmcp.com/<app_path>/`.
`finch run [--config finch.yml]`	Serve every ingress rule in `finch.yml`. Auto-approves services while you are logged in.
`finch enroll <app_path> --ticket <t>`	One-time: trade a dashboard ticket for a saved box credential. Use `--ticket -` to read the ticket from stdin, or set `FINCH_TICKET`.

Enrolling a second box needs no browser. From a box that is already logged in:

finch token | ssh user@newbox "finch login --token -"
ssh user@newbox "finch add api --service http://127.0.0.1:9000 && finch run"

Inspect

Command	What it does
`finch status [--json]`	Show whether you are logged in (and to which tenant), and what the local `finch.yml` serves.
`finch fleet [--json]`	List every service in the account with its state (online, offline, pending). Alias: `finch ls`.
`finch guide`	Print the full agent operating manual.

Keys and tokens

Command	What it does
`finch token [--json \| --login]`	Mint a fresh CLI token from an authed box, for provisioning a new box without a browser. `--login` prints a ready-to-run `finch login` command.
`finch keys mint <label> --service <id>`	Mint a client `finch_` key scoped to one service. The key prints once. `--all` scopes it to every service instead.
`finch keys list`	List client keys (id and label).
`finch keys revoke <id>`	Revoke a client key. Access stops immediately.
`finch revoke-tokens`	De-authorize every CLI login, including the box you run it on. Every box must `finch login` again.

Two kinds of credentials. The CLI token is a tenant-admin credential (about 30 days) that the box itself uses. finch_ keys are what clients present to reach your services. See Keys & auth.

Endpoints

Command	What it does
`finch test <service>`	List the service's MCP tools through the hub. A quick does-it-work check.
`finch call <service> <tool> [--args '{...}']`	Invoke one MCP tool through the hub. `--args` takes a JSON object.

finch test printer
printer — 2 tool(s):
  • echo             Echo the input back
  • print            Send a document to the printer
finch call printer echo --args '{"text":"hi"}'
hi

Manage

Command	What it does
`finch rm <service>`	Remove a service from the account.
`finch approve <app_path>`	Clear a service's pending gate. Only needed when you are not logged in; `finch run` approves automatically otherwise.
`finch auth <app_path> public\|key`	Set whether the public endpoint requires a `finch_` key. `public` makes it an open webpage.
`finch update [--force]`	Self-update the binary from the hub and restart the running serve cleanly. `--restart auto\|service\|self\|none` controls how.
`finch domain ls`	List custom hostnames mapped to the account. `finch domain add <hostname>` and `finch domain rm <hostname>` manage them. See Domains.

JSON output

--json is supported on add, token, status, fleet, keys, test, and call. Use it for scripting and agents.

finch status --json
{
  "loggedIn": true,
  "hub": "https://finchmcp.com",
  "tenant": "your-slug",
  "config": "finch.yml",
  "ingress": [{ "app_path": "printer", "service": "http://127.0.0.1:8000" }]
}

finch.yml

finch add writes this file. It holds no secrets; credentials are saved separately under ~/.finch/.

hub: https://finchmcp.com
box: this-box
ingress:
  - app_path: printer                # becomes <slug>.finchmcp.com/printer/
    service: http://127.0.0.1:8000

← Domains Quickstart →