Curviate Quickstart

Curviate: the first run

Four steps, in this order: install, authenticate, connect an account, prove it. Every command here is a read. Nothing in this skill posts, messages, invites, follows or endorses anyone.

Established against CLI 0.33.0.

1. Install the CLI

npm install -g @curviate/cli
curviate --version    # needs Node 18 or newer

2. Authenticate this machine: curviate setup

setup opens the dashboard, takes the short code it shows you, and saves an API key into a local profile. The key is never printed and never passed on a command line.

The command has two shapes, and which one you get is decided by whether stdout is a terminal.

Agent shape: two legs, because a browser has to happen in between

When stdout is not a terminal, or when --json is passed, setup prints a JSON object and exits 0. It does not prompt and it does not open a browser:

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

Open authorize_url in a browser signed in to the workspace, press Authorize, and read back the code it displays. Then hand that code to the second leg on stdin:

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

• --code - reads from stdin deliberately. Passing the code as a flag value works but warns: a value on the command line is visible to other processes through ps and is saved in shell history.
• The two legs must run on the same machine, under the same configuration directory. Leg one writes a short-lived resume file beside the config file, readable only by you, holding the session id and the private key that opens the delivered credential. Leg two reads it and deletes it. Split the legs across machines, users, containers or config-directory overrides and the exchange cannot complete.
• --code - with no setup in progress exits 2 and says so. Run leg one first.
• The code is short, case-insensitive, and drops anything that is not one of its own characters, so a pasted code with stray spaces or punctuation is still accepted.

Human shape

With stdout on a terminal and no --json, setup prints the link, opens a browser, and prompts for the code (up to three attempts). --no-browser prints the link rather than opening it, which is what you want over SSH or anywhere a browser would open on the wrong machine.

One asymmetry to know before scripting it: stdout on a terminal with stdin piped is refused at exit 2, because there is nowhere to paste a code into. It names CURVIATE_API_KEY and curviate login --api-key - as the alternatives. A fully piped invocation is not that case: it is the agent shape above, and it exits 0.

What each failure means

A code is short-lived and allows only a handful of attempts. If in doubt, start a fresh setup rather than reusing anything.

3. Confirm: curviate doctor

curviate doctor --json

It reports the CLI version, the config path, the active profile, the base URL, where the credential resolved from, which workspace it authenticated as, whether the API is reachable, whether the credential is accepted, and every connected account with its status.

Three things that surprise people:

• Run setup first, then doctor, not the other way round. Reachability is only tested through a real call, so with no credential resolved doctor reports the API as unreachable. That is not a network problem; there was nothing to call with.
• The workspace line is populated only for a credential setup wrote. A key supplied through the environment or login authenticates perfectly well, but doctor has no name to show for it and says so. And where a name is shown it identifies the workspace; it is not promised to be a friendly, human-chosen label.
• Zero connected accounts is a pass, not a failure. doctor reports 0 connected and exits 0. That is the expected state of a workspace nobody has connected an account to yet.

doctor reports rather than throws, so it prints a report and not an error envelope. Branch on the exit code and read checks[] for which stage failed:

• 0: every check passed.
• 2: the request was refused before it was sent, so nothing reached the network. An empty credential, or a malformed base URL (the report's detail reads Invalid base URL: expected an absolute http:// or https:// URL). Fix the invocation or the value; a retry cannot help.
• 3: no credential resolved, or one resolved and was rejected. Run setup.
• 7: the API could not be reached, or was reached and answered with a platform fault. Both are worth a retry.

This list is not exhaustive, and the codes beyond it are not doctor's own. The credential check is a real API call, and whatever refusal comes back is passed straight through, so any code the API can produce can surface here. The one a first run meets most often is exit 5 on a workspace with no active seat: the credential is fine and the network is fine, and no amount of re-running setup will change it. Look an unfamiliar code up in the area skill for the surface you are about to use: each ends with a table of the codes its commands produce and the action each implies.

The checks[] entries separate the three stages, and the wording is exact: api reachable reading not checked means the request never left this machine, while could not reach means it left and found nothing. credential valid reading not checked means nothing asked the credential anything; it is not a verdict on the credential, so do not go looking for a bad key on the strength of it.