Connecting providers from the CLI

receipt connect <provider> authorizes a provider — one of the connectable apps in the catalog, such as GitHub, AWS or Google Drive — in your browser, and stores the resulting connection in the workspace your CLI session is bound to. The credential itself stays on the server; what lands in the workspace is a reference to it. Signing in always lands you in your organization’s Default workspace; after receipt workspace use <name> your session carries a token for that workspace instead, and every connect command — authorizing, status, disconnect — then reads and writes there. Connections you made in another workspace stop appearing in receipt connect status until you switch back. To place a connection from the browser instead, see Connect an app. receipt connect status, disconnect and <provider> reuse the session saved by receipt setup; being already signed in means no second browser prompt. If the gateway rejects that saved token (HTTP 401) the CLI signs in once more and retries, rather than failing.

Authorizing a provider

receipt connect github

The command reuses your saved session, then creates an authorization session and prints the link:

Step 2 of 2: authorize github
  Open: https://<connect-host>/...
  Press Enter to open github authorization...

The link is minted by the deployment’s integration provider and passed through unchanged apart from an apiURL parameter Receipt appends, so its exact shape depends on that provider. If no link comes back, the command stops with Nango did not return a connect link. On a TTY it pauses at that prompt before opening your browser. --yes or --auto-open skips the pause. With browser auto-open disabled it prints Browser auto-open is disabled; open the URL above to continue. instead. Unless you pass --no-wait, it then prints Waiting for github authorization to complete... and polls GET /connect/connections every 2 seconds until a connection for that provider reports status valid. The default budget is 10 minutes. The three endings you can get:

receipt connect: github connection 'default' is ready for server jobs.

Timed out waiting for github connection.

After authorization completes, run 'receipt connect status' to verify the github connection.

The last one is what --no-wait gives you.

Polling matches any valid connection for that provider, not specifically the one you just authorized. If a valid connection for the provider already exists, the command returns immediately.

Flags

Flag	Default	Effect
`--email <addr>`	none	Sent as the end-user email on the authorization session
`--yes`, `--auto-open`	off	Skip the “Press Enter” pause
`--no-wait`	off	Return as soon as the link is opened, without polling
`--timeout-ms <n>`	`600000`	Polling budget in milliseconds
`--no-open`	off	Print the link only, do not open a browser
`--fresh-login`	off	Ignore the saved session and re-run the browser sign-in

--wait=false is not a working form of --no-wait; use --no-wait. A target word or URL may follow the subcommand — receipt connect status local, receipt connect aws dev, receipt connect github https://gw.example.com — alongside the shared --server-url, --auth-url and --no-open flags.

What the server can refuse

Creating the authorization session requires the connect:write scope and workspace mutation authority. The refusals you may see:

workspace_membership_required (403) — your token is not a member of that workspace, or is a member without authority to mutate it. Mutating needs the workspace owner or admin role, or organization owner or admin.
Self-hosted Nango is not configured. Set RECEIPT_INTEGRATIONS_URL, RECEIPT_INTEGRATIONS_SECRET_KEY, and RECEIPT_INTEGRATIONS_WEBHOOK_SECRET. (503) — the deployment has no integration provider configured.
Unsupported connector. Use one of: aws, gcp, ..., or any integration configured in Nango. (400) — the request named no integration the gateway could resolve. The CLI resolves the connector word before it sends anything, so this one reaches you only from other callers of the API.

An unrecognised provider word fails client-side first, with unsupported Receipt Connect provider. Use aws, gcp, google-ads, .... If a connection already exists for that provider and name, Receipt creates a reconnect session against the existing record rather than a new connection.

Two behaviours worth knowing before you start

The numbered menu breaks for most connector labels

Running bare receipt connect prints an interactive menu:

Receipt Connect onboarding
Credentials are approved with your Receipt account and stored for the active workspace only.
The CLI will show account metadata, not secret values.
Signed in: you@example.com
Workspace: Default (<workspaceId>)
Current connections: none
What do you want to connect?
  1. AWS
  2. Google Cloud
  ...
  64. Show status only
Choose [1]:

The menu has 64 entries: one numbered line per connector label — 63 of them — with Show status only last.Picking a number returns the display label, lower-cases it, and looks it up in the alias map. Only 25 of the 63 labels happen to match an alias: AWS, Gmail, Notion, LinkedIn, GitHub, HubSpot, Airtable, Apollo, Attio, Zendesk, GitLab, Slack, Linear, Datadog, Sentry, Cloudflare, Vercel, Incident.io, Azure, Anthropic, OpenAI, Zoom, ZoomInfo, Zoho and Outlook. The other 38 — every Google product, both Jira labels, both Confluence labels, Terraform Cloud, Azure DevOps, the nine Zoho product labels, the TikTok labels, Azure Blob Storage and the rest — fail before any request is sent:

unsupported Receipt Connect onboarding choice: Google Cloud

Use the connector identifier instead: receipt connect gcp, or --provider gcp. The connector catalog lists the ids. In a non-TTY the menu picks the default, index 1 — AWS.

Every CLI-created connection is named default

The released CLI sends no connection name, so the server always stores the connection as default. There is no --name flag on the provider flow.Named connections such as aws.prod exist in the data model and are usable — receipt tools --connection aws:prod, capability key aws.prod — but nothing in this release lets you choose the name. The browser flow stores default too; the one non-default name the product creates is agent-registry, from the Agent Registry cloud dialog, and the workspace integrations list hides it. See Connect an app.

Checking what is connected

receipt connect status

Prints one line per connection in the session’s workspace, with whatever account, principal and expiry detail the provider reported:

receipt connect status:
Current connections:
  aws:default valid - account <account-id> / <principal> / expires <timestamp>
  github:work valid

With nothing connected in this workspace:

receipt connect status: no server-side connections configured

Errors surface as unauthorized, workspace_membership_required, receipt_connect_storage_unavailable or HTTP <n>.

Removing a connection

receipt connect disconnect --provider github --name default

disconnect, remove and revoke are the same command. Its defaults are --provider aws --name default — running it bare targets your AWS connection, not the last provider you touched. It finds the matching connection and deletes it:

receipt connect disconnect: removed github:default

receipt connect disconnect: no github:default connection found

Deletion needs connect:write and workspace mutation authority. If the integration provider refuses the delete, the gateway answers 502 integration_connection_delete_failed.

The agent surface: `list`, `tools`, `call`

receipt connect list, receipt connect tools and receipt connect call are a separate surface intended for automated callers. On the released binary they also use your saved session, so they work straight after receipt setup. When RECEIPT_CONNECT_TOKEN and RECEIPT_CONNECT_GATEWAY_URL are set, those environment variables take precedence over the saved session — the way to give a sandbox or CI job an explicit identity. Two things make this surface and receipt connect status disagree about what is connected: an environment token can be bound to a different workspace than your saved session, and list returns only connections that are provider-backed and valid, while status returns every stored connection with whatever status it has. Gateway URL comes from --server-url, RECEIPT_CONNECT_GATEWAY_URL or RECEIPT_PROXY_SERVER_URL; the token comes from RECEIPT_CONNECT_TOKEN. Signed out with no environment override:

Receipt Connect gateway is unavailable; run 'receipt setup' or set RECEIPT_CONNECT_TOKEN

On this surface a saved token is only ever sent to its own gateway host — the origin it was minted for. It is never forwarded to a different --server-url or environment gateway.

Command	Output
`receipt connect list [--json]`	`Current connections:` with one `<provider>:<name> <status>` line each, or `Current connections: none`
`receipt connect tools <connection>`	`{ok, connection, tools}`, where each tool carries a name, an optional description, `access` of `read` or `write`, and an input schema
`receipt connect call <connection> <tool> [--json '{...}']`	`{ok, connection, tool, access, result, artifacts}`
`receipt connect call <connection> --path /x [--query-json '{...}'] [--headers-json '{...}']`	`{ok, connection, status, headers, data}`, where `data` is the provider’s response

The two call forms

call has a named tool form and a read-only GET form. The named tool form takes a tool name plus --json '<object>' for its arguments. The GET form takes --path and reads a provider-relative resource directly; every such call is recorded as a tool receipt named <connection>:GET <path>. The server enforces most of the rules, not the client, so these come back from the gateway:

path must be a safe provider-relative absolute path — the path starts with a single / and is at most 4096 characters, with no backslash, no #, no . or .. segment, no encoded slash, and no /http: or /https: prefix
body is not allowed on read-only integration calls
header '<x>' is not allowed
query '<k>' has an unsupported value
integration action '<tool>' requires connect:write
integration action not found or disabled (404)

Write operations stay off until an owner or admin enables them for that connection; there is no per-action approval prompt in this release. See Tools and permissions. Client-side checks fire first, before any request is sent: receipt connect tools requires a connection id or provider:name, receipt connect call requires --path beginning with /, receipt connect call is read-only and supports GET only (any --method other than GET), --json must contain valid JSON and --json must contain a JSON object. A connection whose credential has gone terminally invalid answers 409 with reconnectRequired: true; reconnect the provider and retry. Next step: call tools and wire up an MCP client.

Get started

Commands

Reference

Developer CLI (from source)

Connecting providers from the CLI

Authorizing a provider

Flags

What the server can refuse

Two behaviours worth knowing before you start

Checking what is connected

Removing a connection

The agent surface: `list`, `tools`, `call`

The two call forms

​Authorizing a provider

​Flags

​What the server can refuse

​Two behaviours worth knowing before you start

​Checking what is connected

​Removing a connection

​The agent surface: list, tools, call

​The two call forms

Authorizing a provider

Flags

What the server can refuse

Two behaviours worth knowing before you start

Checking what is connected

Removing a connection

The agent surface: `list`, `tools`, `call`

The two call forms