Signing in

On your own machine you approve the CLI once in the browser and never handle a token. Agents and CI get a key of their own. This page is the whole picture: what happens, where things live, and how to undo them.

Two ways to be signed in

When both are present, the environment variable wins. That is deliberate: an agent running inside your shell must never quietly act as you. colophon whoamialways says which one is in use.

What colophon login does

colophon login

In the terminal:

Open https://app.colophon.fyi/cli/authorize?code=WQ7K-4H2P
and confirm the code  WQ7K-4H2P
(opening your browser…)
Waiting for approval…

The browser opens that link. If you are not signed in to the dashboard you sign in first — Google, GitHub or an emailed link, as usual — and come straight back. The page then shows exactly what is being asked for:

Check that the code on the page matches the one in your terminal and that the machine is yours, then click Approve. Within a couple of seconds the terminal finishes:

✓ Signed in as you@example.com · workspace acme (owner)
Saved to /Users/you/.config/colophon/credentials.json

• The link is valid for ten minutes and works once. Reopening it afterwards says the code is no longer valid.
• The session is bound to whichever workspace was active in your browser when you approved. Switch later if that was the wrong one.
• Over SSH, or anywhere a browser can’t open, run colophon login --no-browser and open the printed link on any device where you are signed in — the approval does not have to happen on the same machine as the terminal.

What a login can do

Exactly what you could do in the dashboard, no more. An owner’s session publishes, manages links, reads traffic and can mint API keys. A member’ssession publishes and reads traffic; asking it to manage links is refused with a message naming the role. Everything it does is written to the audit log under your name, not a key’s.

Where the session lives

The file is created readable only by you (0600) and holds the session token plus the user and workspace it was issued for, so whoami can answer without a network round trip. Treat it like an SSH key: don’t commit it, don’t copy it between machines — run login on each one instead, so each has its own revocable session.

Several workspaces

colophon switch            # list your workspaces; * marks the active one
colophon switch acme       # publish into acme from now on

A login points at one workspace at a time. Switching changes both the server-side session and the local file, and whoami confirms the change.

Signing out and revoking

colophon logout

Revokes the session on the server and deletes the local file. If the server can’t be reached the file is removed anyway, and you revoke from the dashboard instead.

Every signed-in machine is listed under Account → CLI sessions with its hostname, when it signed in, when it last did anything, and when it will expire. Revoke ends one immediately: the next command on that machine fails with your session has expired and asks for a fresh login. Use this for a lost laptop or a machine you no longer have.

Agents, CI and servers

A machine with no browser cannot log in — and shouldn’t act as a person anyway. Give it an API key: minted from your own signed-in terminal, or under API keys in the dashboard. Keys are owner-only to create, shown once, and scoped.

colophon create-token --name publishing-agent --scopes publish,links
# → colo_live_…   (shown once)

Then, in the agent’s environment — not your own shell profile:

export COLOPHON_TOKEN=colo_live_…

With the variable set, every command uses the key and nothing is written to disk. The key appears under API keys like any other, recorded as created by you, and can be revoked there. Keys cannot mint further keys; if an agent needs a different scope, mint it a new key.

When something goes wrong

Full command details are in the CLI reference; how keys and roles fit together is in Workspaces, members & keys.