Platform and auth
This page documents the commands that manage who you are and where your work goes: signing in and out, checking your identity, listing projects, and saving a default project. It ends with the full list of platform areas that have no CLI command at all.
Command summary
| Command | What it does |
|---|---|
platformctl login | Sign in and cache a 12-hour session token |
platformctl logout | Discard the cached token |
platformctl whoami | Show who you are and which credential the CLI is using |
platformctl projects list | List the projects you can access |
platformctl config set-project | Save a default project |
platformctl config get-project | Show the saved default |
platformctl config view | Show the config file path and contents |
platformctl login
Signs you in with email and password and caches the session token so later commands can use it.
platformctl login [--email <email>] [--password <password>]
| Flag | Default | What it does |
|---|---|---|
--email | $CAI_USER | Your account email. Accounts are created by an administrator or via an invitation link — there is no self-service sign-up. |
--password | $CAI_PASSWORD | Your password. |
Example:
platformctl login --email you@example.com --password 'your-password'
You should see:
signed in as you@example.com; token cached
The token is written with owner-only permissions to <UserConfigDir>/crusoe-ai/token (macOS: ~/Library/Application Support/crusoe-ai/token; fallback: $TMPDIR/crusoe-ai-token). Sessions last 12 hours; after that, log in again.
Errors you may hit:
- Missing credentials:
need an email and password: pass --email/--password, or set $CAI_USER/$CAI_PASSWORD
- Wrong email or password — the server returns one deliberate, undifferentiated message for both, so account existence cannot be probed:
invalid email or password
- Too many attempts (the server throttles sign-ins per IP and per account):
too many sign-in attempts; try again in <duration>
If your account was created with a temporary password, login still caches a token but tells you the account must change its password before it can manage anything. Set a new password in the web console at https://console.codyhill.dev, then log in again. Until then, every management command returns 403 with password change required before using this API.
platformctl logout
Deletes the cached token.
platformctl logout
platformctl logout
You should see:
cached token discarded (note: $CAI_TOKEN and the automation token, if present, still apply)
That note matters: logout only removes the cached login. If $CAI_TOKEN is set, or the cluster's automation token is reachable, the CLI will keep authenticating with those. Session tokens are stateless and cannot be revoked server-side before their 12-hour expiry.
platformctl whoami
Shows who the platform thinks you are and which credential the CLI found.
platformctl whoami
platformctl whoami
You should see:
you@example.com role=user (credential: cached login (~/Library/Application Support/crusoe-ai/token))
The role shown is your effective role, re-read from the server — not whatever your token claims. If no credential is found:
not authenticated (management commands will fail; invoking agents still works)
platformctl projects list
Lists every project you can access. A project is the isolation unit everything you create belongs to.
platformctl projects list
platformctl projects list
You should see a table with the columns SLUG, NAME, SHORT, ROLE, and ID:
SLUG NAME SHORT ROLE ID
ml-team ML Team ab12cd admin 1c9a...
ROLE is your resource role in the project (admin or member) — your authority over the project's contents. SHORT is the project's immutable short id, used in namespaces and hostnames; it never changes, even if the project is renamed.
platformctl config
Manages the CLI's saved default project, so you do not have to pass --project on every command.
config set-project
platformctl config set-project <project>
platformctl config set-project ml-team
You should see:
default project set to ml-team
Pass an empty string to clear the default:
platformctl config set-project ""
$CAI_PROJECT overrides the saved default, and the --project flag overrides both — the same layering as gcloud, aws, and az.
config get-project
platformctl config get-project
Prints the saved default project, if any.
config view
platformctl config view
Prints the config file's path and the saved default_project. The file is <UserConfigDir>/crusoe-ai/config.json, written with 0600 permissions, containing {"default_project":"..."}.
Using an API key instead of logging in
For scripts, CI, and service accounts, skip login entirely. Create an API key (format cai_<keyid>_<secret>) in the console — see service accounts and API keys — and export it:
export CAI_TOKEN=cai_xxxxxxxxxxxx_...
platformctl whoami
You should see:
ci-deploy@ab12cd.cai.local role=user (credential: $CAI_TOKEN)
$CAI_TOKEN is checked first, ahead of every other credential source. A key acts as its owner, re-resolved on every request: if the owner loses a grant, the key loses it on its next call. Revocation is immediate. The CI/CD tutorial walks through the full setup.
Two more credential sources exist below $CAI_TOKEN and the cached login: $CAI_USER + $CAI_PASSWORD (the CLI logs in on the spot, caching nothing), and the cluster's automation token (read via kubectl from the cai-automation-token Secret — a cluster-admin convenience). The full resolution order is on the CLI overview.
Console/API only
The following platform areas have no platformctl commands. Manage them in the web console at https://console.codyhill.dev or through the REST API.
| Area | Where to do it |
|---|---|
| Organizations (create, delete, org members) | Console/API only — projects and access |
| User administration (create, roles, password resets, delete) | Console/API only — projects and access |
| Project create, rename, delete | Console/API only — projects and access |
| Project members and invitations | Console/API only — projects and access |
| Break-glass access | Console/API only — break-glass and audit |
| Audit log | Console/API only — quotas and audit |
| Quotas | Console/API only — quotas and audit |
| Service accounts | Console/API only — service accounts and API keys |
| API keys (create, revoke) | Console/API only — service accounts and API keys |
| MCP servers (create, publish tools, versions, rollback) | Console/API only — MCP servers |
Platform model key (/v1/profile) | API only, platform admin — platform API reference |
| Password change | Console only (the CLI has no change-password command) |
The CLI consumes several of these: an API key minted in the console drives the CLI via $CAI_TOKEN, and the project you pick with config set-project was created in the console. For every endpoint behind these areas, see the platform API reference.