CLI authentication and targets

Select credentials and a project separately

An authentication profile selects the credentials and site used for a request. A project selector chooses the project within that context. A browser selector chooses a browser session. Setting one does not prove the other two are correct.

For work from your own computer, start with the CLI quickstart, then keep the profile explicit:

cocalc --profile cocalc-ai --json auth status --check
cocalc --profile cocalc-ai project get --project PROJECT_ID

Replace PROJECT_ID with a project ID from project list. Inspect the account, site, project ID, and title before a write.

Saved profiles and environment authentication

Profile selection follows:

1. The explicit --profile option.
2. COCALC_PROFILE, when set.
3. The current saved profile, or the environment profile when COCALC_CLI_AGENT_MODE=1.

Use --profile env to select environment-based authentication explicitly. For an existing saved profile, explicit command-line options override saved values, and ambient authentication defaults are disabled. A saved profile's API URL therefore takes precedence over the environment API fallback.

If you explicitly change --api to another origin, credentials stored for the profile's original origin are not inherited. Sign in to the intended site using its own profile instead of assuming a saved login applies everywhere.

cocalc auth --help
cocalc --profile cocalc-ai auth status
cocalc --profile cocalc-ai auth status --check

Status output is diagnostic information, not something to paste into a public issue without review. Check data.check.ok when using JSON. See scripting and results.

Project context is local to the directory

cocalc --profile cocalc-ai project use --project PROJECT_ID
cocalc --profile cocalc-ai project get
cocalc project unuse

project use writes .cocalc-project in the current local directory. project unuse removes that selection. The general project resolver reads the current directory's context; it does not search parent directories. An explicit --project takes precedence.

Names are convenient interactively, but full project IDs are more reliable in automation. Do not assume COCALC_PROJECT_ID is a universal replacement for --project: environment targeting is supported by particular command and agent paths, while the general resolver uses an explicit target or local context.

Use the authentication supplied to a CoCalc agent

CoCalc agent sessions may already carry scoped credentials, project context, and a browser ID. Check that context before starting a separate login flow. A personal account profile stored in a shared project can expose account access to collaborators; use the supplied project or agent identity there.

For local source development, load the environment for the running server in the same shell before CLI operations:

cd src
eval "$(pnpm -s dev:hub:env)"

For a Lite development server, use dev:lite:env instead. Refresh this environment after restarting or switching servers. These are repository development commands, not installation steps for users of the hosted site.

Login, elevation, and bootstrap serve different purposes

When an operation reports that fresh authentication is required:

cocalc --profile cocalc-ai auth elevate

Follow the printed browser approval and passkey or TOTP challenge. The default elevation lasts eight hours; --short requests fifteen minutes. To perform login, elevation, and verification together on your own computer:

cocalc --profile cocalc-ai --api https://cocalc.ai auth bootstrap

API keys, bearer tokens, and project-scoped credentials do not replace the cookie-backed interactive session required for fresh authentication. An unattended script should report the approval requirement to its operator. Do not repeatedly retry an approval-dependent operation as though it were a temporary network failure.

Match the credential to the command

A CoCalc account API key is limited by its capabilities and project scope. Limiting it to one project does not make it the project's runtime identity. See the HTTP API guide for key scope and endpoint usage. The current CLI's Hub account and admin calls do not accept account API-key authentication, even when the key works with an HTTP endpoint. Use a browser-approved account profile for those calls, with the required account or admin permissions.

Project runtime credentials and scoped agent tokens have their own permitted operations. Changing --project does not broaden that identity's access. A project OpenAI API key configured for Codex supplies OpenAI access; it does not sign the CLI in to CoCalc.

Fresh authentication is a separate check from whether a command reads or changes data. With an account profile, for example:

Use the supported credential for each command and handle permission errors separately from expired approval. Elevation does not grant an admin role or expand an API key's capabilities. Use --help to inspect a command before scheduling it; plan for any required approval even when the command is a read.

Plan authentication for host commands

Host inventory and lifecycle commands require an account identity with the appropriate host permissions. Project or managed-agent credentials do not by themselves grant account access. A successful auth status --check verifies the effective connection; it does not prove that every command is permitted.

The CLI's automatic fresh-auth prompt requires an interactive terminal on both standard input and standard error. A noninteractive job should report the approval requirement and stop that operation. Elevation can expire before a later scheduled run. Prepare the required approval before a deliberate operation, and keep an operator-visible path for failures; a saved profile or schedule does not renew approval automatically.

Select the identity for managed VM commands

Managed VMs are an optional site feature. Their command scope differs from project-host commands, so check the identity supplied to the CLI before reusing a host automation script.

These are authentication boundaries, not a guarantee that every account API key or token can call every method. Server permissions, agent grants, resource state, and admission rules still apply. For a human account, vm stop does not add the fresh-auth check used by vm start; host stop has its own fresh-auth requirement. Treat both stops as operations that interrupt running work.

From your own computer, with an account profile already set up for the intended site, inspect the scope before a mutation:

cocalc --profile cocalc-ai --json vm list --all
cocalc --profile cocalc-ai --json vm list --project PROJECT_ID

Replace PROJECT_ID with the project you intend to inspect. A scoped agent should keep its supplied identity rather than storing this personal account profile in a collaborative project. A VM appearing in a listing does not itself establish SSH access or permission to start or stop it.

Printing a VM connection command can still prepare access

For vm ssh and vm rsync, --print and JSON output return the generated connection command instead of launching the local SSH or rsync process. They still request SSH-key authorization first. That request can add or reconcile access on the VM; adding a new account SSH key can require fresh authentication. Project and agent routes retain their own access, approval, and deploy-key checks. These options are therefore not a read-only connection preflight.

Use command help to inspect syntax without requesting access:

cocalc vm ssh --help
cocalc vm rsync --help

When recording JSON output in an unattended workflow, distinguish a returned connection command from an executed remote command or completed file transfer. Run the intended transport and verify the remote result separately when that operation is authorized.

These selection and command-preparation paths were checked locally on 2026-09-12 against CLI source version 1.0.3 with synthetic service adapters. No live account authorization, VM start/stop, SSH connection, or file transfer was performed by those checks.

Browser targets need their own check

Start with discovery and resolution before sending browser actions:

cocalc browser session list --help
cocalc browser target-resolve --help

Use explicit project and browser selectors supported by the command. Browser availability and permissions also depend on the running site and session; a valid account login alone does not establish that a browser action can run.