Integration setup (CLI)

Set up integrations and inspect their configuration readiness from the CLI.

The CLI exposes two integration commands: outlit integrations setup and outlit integrations status. Both use the public tool gateway. For personal connections, the API key needs integrations:connect_own. Workspace setup needs integrations:manage. Outlit determines which permission applies to each provider and request.

Integration setup

outlit integrations setup hubspot
outlit integrations setup hubspot --json

Setup checks the provider capabilities without sending credentials. If the response includes preferredSetupVersion: 1, the CLI uses outlit_setup_integration. Older server versions use a browser handoff; the CLI does not send credentials or provider settings to that flow.

Interactive setup can:

• Prompt for a provider credential only after the Outlit server returns CREDENTIAL_REQUIRED. Secret prompts disable terminal echo.
• Open a validated browser handoff on the configured Outlit origin. Authentication handoffs are polled for at most five minutes. Recovery and external setup open in the browser; the CLI does not wait for them to finish.
• Display a CRM recommendation and submit that exact mapping after confirmation.
• Display a Mixpanel preview and submit the exact mapping selected by the user.

If setup repeats a credential, authentication, or mapping step, the CLI stops with SETUP_STALLED. If it cannot open a validated handoff URL, it prints the URL so you can open it yourself.

Setup has no provider-secret flags. Never place provider credentials directly in command-line arguments, where process listings and shell history can expose them.

Automation and JSON mode

Use --config-stdin to opt into reading exactly one strict JSON object from stdin. Its shape is provider-specific. For example, a Fireflies API key is supplied only through stdin:

printf '%s\n' '{"credentials":{"apiKey":"<fireflies-api-key>"}}' \
  | outlit integrations setup fireflies --config-stdin --json

An explicit HubSpot CRM mapping is likewise supplied as the generated CRM mapping shape:

printf '%s\n' '{"configuration":{"kind":"crm_mapping","mappings":[{"pipelineId":"default","pipelineName":"Sales","mappings":[{"outlitStage":"Won","crmStages":[{"id":"closedwon","name":"Closed Won"}]}]}],"confirm":true}}' \
  | outlit integrations setup hubspot --config-stdin --json

The provider remains the positional CLI argument and is rejected inside the stdin document. Unknown top-level fields are also rejected. --config-stdin is explicit; ordinary piped stdin is not read.

JSON mode never prompts, opens a browser, or polls. It returns the raw setup result for handoffs and configuration previews. If credentials are required but were not supplied through --config-stdin, the command exits nonzero with Outlit’s stable CREDENTIAL_REQUIRED error.

For a CRM recommendation, --accept-recommended submits the exact recommendation from the current response. It conflicts with a custom CRM mapping supplied through stdin. A Mixpanel mapping must be supplied as an exact, confirmed configuration in headless mode.

Expected provider credentials are never returned in command output. Handoff URLs must match the configured Outlit origin, use HTTPS except for loopback development, and contain no URL credentials, fragments, or secret-bearing query parameters.

Integration status

outlit integrations status
outlit integrations status hubspot --json

status calls outlit_get_integration_status and returns one of five configuration-readiness states:

State	Meaning
not_connected	No usable provider connection exists.
awaiting_auth	Authentication must be completed.
setup_required	Provider configuration or mapping remains.
ready	Required authentication and configuration are complete.
requires_intervention	Setup needs human attention or repair.

ready describes configuration readiness only. It does not promise that a sync or backfill has finished, that customer data is present, or that provider data is current. The status command does not expose browser-session, raw provider-state, sync, or action metadata. gmail is accepted as a CLI alias for google-mail.