Accounts

cora signs in to your CORA account through the CORA service at https://cora.vispero.com. The cora auth commands sign in and out, and show the account and its token. The CLI reference lists their options. The service’s site shows your account too, and creates the CI tokens that CI systems sign in with.

What needs an account

Each command’s Needs an account line in the CLI reference says whether it needs your account. Every tool cora-mcp gives a coding agent needs it too, the browser_* tools included. A build that registers CORA’s build plugin, such as @vispero/cora/vite, and a config typed with @vispero/cora/config, need none.

A command or tool that needs the account checks it first:

• Without a credential, a command fails with account.missing and exit code 2, naming cora auth login as what to run. A cora-mcp tool answers with that error, and cora-mcp keeps serving and listing its tools.
• A token that has expired fails with account.expired, and one that does not verify with account.invalid.
• When the CORA service does not answer, the check fails with the service.* error that says why, such as service.unreachable. cora asks the service only to renew a signed-in token, or to fetch its current signing keys.

Signing in

npx cora auth login

cora auth login prints a page and a code:

To sign in:
  Open https://cora.vispero.com/device and enter the code WDJB-MJHT

Open the page on any device, sign in there, and enter the code. On a desktop, cora also opens the page in your default browser, with the code filled in. It opens none in CI, over SSH on macOS and Windows, or on Linux without a display: open the page yourself there. Under WSL and in a coding agent’s shell, it tries, and prints the page either way.

cora waits until you approve the login. Then it saves the credential, and prints the account’s organization, by name and ID, and its plan:

Signed in: organization Acme (org_01JZ8Y1C3E5G7J9K2M4P6R8T0V), plan team

• A login you deny, or whose code expires first, fails with account.login-failed. Run the command again.
• cora accepts a sign-in page only on https://cora.vispero.com, and refuses any other the same way.
• A signed-in credential renews itself. When cora checks the account and the token expires within the hour, it renews the token with the refresh token it saved beside it.

Checking the account

npx cora auth status

cora auth status prints the CORA service and your account there on stdout, with when the token expires and where the credential comes from:

Service: https://cora.vispero.com
Account: valid
Organization: org_01JZ8Y1C3E5G7J9K2M4P6R8T0V
Organization name: Acme
Plan: team
Expires: in 23 hours
Source: /home/ada/.config/cora/credentials.json

Without a credential, it fails with account.missing and exit code 2.

cora reads the organization’s name from the token, as it was when the token was issued, so a CI token keeps the name it was created with. When the token does not carry the name, Organization name reads unknown, and cora auth login prints the organization’s ID alone.

Printing the token

npx cora auth token

cora auth token prints the account token on stdout, alone and followed by a newline, for a script that needs it, as gh auth token prints a GitHub token. For example, to give a container that cannot sign in the token of your login:

export CORA_TOKEN="$(npx cora auth token)"
docker run -e CORA_TOKEN my-image npx cora scan

• Before it prints a signed-in token, cora checks the account, and so renews the token when it expires within the hour.
• When CORA_TOKEN is set, it prints that token instead, which is never renewed.
• It prints only a token that verifies. Otherwise it fails as the account check does, such as with account.missing and exit code 2.

Caution

The token stays out of cora’s stderr and logs, but what cora auth token prints is a secret. Pass it on through a variable or a file, never on a command line, which shell histories and process lists keep.

Signing out

npx cora auth logout

cora auth logout removes the saved credential, or says you were already signed out when there is none. When CORA_TOKEN is set, it says so: the variable still provides a credential until you unset it.

Signing in on the site

Sign in at https://cora.vispero.com with Sign in, at the top of every page. The site then shows your account page, at https://cora.vispero.com/account: your name, your organization and its plan. Sign out, at the top of every page, signs you out of the site.

Saving a token with --with-token

cora auth login --with-token reads an account token from stdin and saves it, without the browser:

npx cora auth login --with-token < token.txt

• It saves the token only once it verifies.
• It reads up to 16 KiB, and waits up to 60 seconds for stdin to end.
• No token, too much input, no end in time, and a token that does not verify all fail with account.invalid, and an expired token with account.expired.
• A saved token is never renewed: it lasts until it expires.

CI tokens

In CI, cora reads a CI token from CORA_TOKEN rather than signing in. A CI token belongs to your organization, which needs a CORA plan. To create one:

1. Sign in on the site, and select Create a CI token on your account page, at https://cora.vispero.com/account/tokens.
2. Choose how long the token lasts, 30, 90 or 365 days, and select Create token.
3. Copy the token, with Copy or from its field. The site shows it only once, and CORA keeps no copy: a token you lose cannot be shown again.
4. Set it as CORA_TOKEN in your CI system’s secrets, as Running in CI shows.

env:
  CORA_TOKEN: ${{ secrets.CORA_TOKEN }}

• cora uses CORA_TOKEN over the saved credential, and never renews it. An empty CORA_TOKEN counts as unset.
• Its name contains TOKEN, so cora keeps its value out of its output and logs.
• When the organization has no plan, the site says so, and creates no token.

A CI token lasts until it expires. cora then fails with account.expired, so create a new one before then and replace the secret.

Create a new one too when cora reports account.invalid after you update @vispero/cora.

Where the credential lives

cora auth login saves the credential in credentials.json, in your per-user config directory, which every cora you run reads, in any project. The user config reference gives where that directory is on each platform. Your user config, config.json, sits beside it, and never holds the credential.

On Linux and macOS, the file is readable and writable by you alone. It holds the token and, after a sign-in in the browser, the refresh token that renews it. cora keeps both out of its output and logs.

Caution

Never commit or share credentials.json.

What CORA sends to the service

cora and cora-mcp check a token on your machine, against the service’s signing keys that each release holds. They reach the service only:

• to sign in;
• to renew a signed-in token;
• to fetch the service’s current keys, when a token was signed by one the release does not hold.

Each request names the client and its version, as User-Agent: cora/<version> or User-Agent: cora-mcp/<version>. Requests go through the proxy your machine names, and trust its certificate store: see Networks and proxies.

• A release older than the oldest the service serves fails with service.client-outdated, and a request the service fails on with service.unavailable: each entry says what to do.