CLI reference

Every finch command, grouped by what you do with it. finch runs on macOS and Linux. Run finch on its own for the list of commands, and finch help <command> (or finch <command> -h) for one command's usage, flags and an example.

By hand, start to finish

finch login                                     # opens the sign-in page and waits
finch add notes --service http://127.0.0.1:8000   # prints the public URL
finch service install                           # keep it running in the background
finch test notes                                # does it answer through finch?
finch connect notes --client claude-code        # add it to your MCP client

Set up

Log in from a script or agent

Plain finch login waits for you and has no --json form. Scripts and agents split it in two, so they can show you the link and keep working:

Connect a client

Each connect makes its own key, labelled with the client and machine, so you can revoke one client with finch keys revoke <id> without touching the others. The client is checked before a key is made, and a key whose setup fails is revoked again. A public service gets no key. Running connect again for Claude Code, Cursor or Codex replaces the entry and revokes the key the old entry used (listed as revoked_key_ids in --json), so re-running it rotates the key. Every Claude Code project on the machine connected to the same service shares the one key file, so they all move to the new key.

See what's happening

Test a service

finch test notes
notes — 2 tool(s):
  • search           Search notes
  • read             Read one note
finch call notes search --args '{"q":"finch"}'

Keys and tokens

Manage

Remove finch

finch uninstall

finch uninstall takes finch off this machine and prints each step as it goes. It:

• stops and removes the background service;
• revokes the keys this machine made with finch connect, and removes the client entries finch added to Claude Code, Cursor and Codex. A machine set up before finch 1.8 kept no record of its keys, so there it revokes none and lists the keys that carry this machine's name for you to check; logged out or offline, it revokes none and says so;
• deletes this machine's login, service credentials and finch.yml from ~/.finch/.

It never deletes the finch binary itself; it prints the command that does. Your account and services stay; finch rm <name> removes a service, and finch revoke-tokens logs out every other machine. With --json it reports each step.

Less common

JSON output and exit codes

Every command takes --json. Success payloads go to stdout and carry "schema_version":1. Lists are wrapped in an object: finch fleet --json prints {"schema_version":1,"services":[…]}. Field names are snake_case. Errors go to stderr as one line:

{"schema_version":1,"error":{"code":"NOT_LOGGED_IN","message":"not logged in","next":"finch login --start"}}

When next is present, it is the command to run next. Exit codes are the same everywhere:

finch status --json
{"schema_version":1,"account":"you@example.com","config":"/Users/you/.finch/finch.yml",
 "hub":"https://finchmcp.com","hub_reachable":true,
 "ingress":[{"app_path":"notes","service":"http://127.0.0.1:8000",
   "url":"https://sunny-wren-42.finchmcp.com/notes/mcp"}],
 "loggedIn":true,"logged_in":true,"login_pending":false,
 "service":{"installed":true,"manager":"launchd","running":true,…},
 "version":"1.8.0",…}

finch.yml

finch add writes this file (at ~/.finch/finch.yml unless the current directory has a finch.yml). It holds no secrets; credentials are saved separately under ~/.finch/.

hub: https://finchmcp.com
box: studio                          # this machine's name
ingress:
  - app_path: notes                  # the service name: sunny-wren-42.finchmcp.com/notes/
    service: http://127.0.0.1:8000
  - app_path: demo
    service: http://127.0.0.1:3000
    forward_all: true                # set by --forward-all