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 whoami always says which one is in use.

Ways into the dashboard#

Your account is your email address. Google, GitHub, Microsoft and an emailed link all sign in to it, and so does your workspace’s own identity provider when it has one (single sign-on). An emailed link to your address always works.

• The first way you sign in makes the account. A provider counts only an address it has verified.
• Another provider is added from the account itself: sign in the way you usually do, then choose Account → Sign-in methods → Add. Signing in with a new one straight from the sign-in page is refused, even when it carries your address, and says so. A provider vouches that an address was verified once, not that whoever holds that account at the provider reads your mail now, and an old work address on a personal GitHub account would otherwise sign in as the person who has that address today.
• Each method added is mailed to your address. If you did not add it, Remove it on the same card: that also signs out every other browser signed in as you. Check the CLI sessions and connected apps listed beside it too.
• Signing in with an emailed link adds nothing you need to manage: opening the link proves the mailbox, which is your account.

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, Microsoft 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 starts in the workspace you picked on that page. Switch later to move it.
• 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. Anyone else’s session does what their role allows (a Publisher’s publishes live, an Editor’s publishes drafts, a Viewer’s reads sites and traffic), and managing links is refused with a message saying their role does not allow it. See Members and roles. 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.