Setup & Doctor

setup and doctor are the CLI's onboarding pair: setup gets a machine authenticated with the least friction, and doctor tells you, in one command, whether everything it needs is actually in place.

curviate setup

setup opens a browser to your dashboard, authenticates as the workspace you are already signed into there, and saves the resulting API key into a local profile. It runs in two legs, because a human has to approve the browser step in between.

curviate setup --json
# {"authorize_url":"...","next_step":"curviate setup --code -","instructions":"..."}

Give authorize_url to your user, ask them to authorize and read back the short code, then hand that code to the second leg on stdin:

printf '%s' "$CODE" | curviate setup --code -
# {"ok":true,"tenant":"...","profile":"default"}

An account_id appears in that object only when the workspace already had a connected account to hand back. A first run does not, so connect one with curviate account link (see the Account page) once setup finishes.

A few things worth knowing before you script this:

• The shape is decided by stdout. Piped, or with --json, setup prints JSON and exits 0. Left on a terminal it prompts interactively instead.
• Both legs run on the same machine, under the same configuration directory. The first leg writes a short-lived local file beside the config; the second reads it and removes it. Splitting the two legs across machines breaks the exchange.
• The verification code is never a standing credential. It works once, expires quickly, and is destroyed after a small number of wrong guesses. Reading it back to an agent is fine; the API key itself never appears in any of setup's output except the local profile file it writes.
• No browser available? setup detects it (CI, an SSH session, no display) and skips the open attempt, printing the URL instead so it can be opened elsewhere, such as on a phone. --no-browser forces that behavior.
• Already have a key? curviate login --api-key - reads one from stdin, or set CURVIATE_API_KEY in the environment; setup is the guided path, not the only one.
• A retry---code - with no run in progress exits 2. Run the first leg again before retrying the second.

curviate doctor

doctor answers one question: can this machine actually call the API right now? Run it after setup to confirm everything landed, or at any point later to check.

curviate doctor --json

It reports, in order: the CLI version; the resolved config path, active profile and base URL; whether a credential resolved and which source it came from (a flag, the environment, or a saved profile, never the value itself); which workspace it belongs to when that is knowable; whether the API is reachable and the credential is accepted; and every connected account.

• Run setup (or login) before doctor, not the other way round. Reachability is tested with a real call, so with no credential resolved doctor reports the API as unreachable. Nothing is wrong with the network; there was simply nothing to call with.
• Zero connected accounts is a pass. doctor reports 0 connected and exits 0. That is the expected state right after setup, before you have linked a LinkedIn account.
• The workspace field is explicit, never silently dropped. A key setup wrote reports the workspace by name; a key from login, CURVIATE_API_KEY or --api-key has no resolvable workspace, and doctor says so in the field rather than omitting it.

doctor exits 0 when every check passes, otherwise the exit code of the first failing check:

That list is not exhaustive: doctor's credential check is a real API call and it passes the API's own refusal straight through, so any exit code the API can produce can surface here. Branch on the exit code, never on the message text.

Errors you may hit

Full envelope shapes are in the error reference.

Next steps

• Account: connect a LinkedIn account once setup finishes.
• Quick Start: install, global flags, and profiles.
• Errors: the full error-code list and what to retry.