Authenticate the CLI

Before any command can reach the Microtica API, the CLI needs an API key. You create one in the Microtica console, store it once with microtica login, and every later command reuses it.

Create an API key

API keys are long-lived credentials for the CLI, SDK, and external automation. A key belongs to the project, not the person who created it — so it keeps working when team members leave, and you can scope it to specific environments and revoke it at any time.

1. Open your project and go to Settings → API keys.
2. Click Create API key.

3. Give the key a Name like claude code or ci pipeline. It appears in the key list and in audit logs.
4. Choose when it Expires — never, in 7, 30, or 90 days, in a year, or on a custom date.
5. Set the Baseline access that applies across every entity in the project (environments, pipelines, apps): None, read, write, admin, or owner. Pick read to let the key use discovery and list endpoints; pick None for a strict per-environment key.
6. Optionally add Per-environment upgrades to grant a stronger role on specific environments. Each upgrade must be strictly stronger than the baseline.
7. Click Create key, then copy the mic_… value — this is the only time it's shown in full.

Back in the list, each key shows its prefix, status, and scopes, and lets you add scopes or revoke it.

Log in

Store your API key with microtica login:

microtica login --token mic_…

You can also pipe the key on stdin, which keeps it out of your shell history:

echo "$MIC_API_KEY" | microtica login

On success the CLI prints where it saved the key. A token that isn't a valid Microtica API key is rejected before anything is written.

Where credentials live

microtica login writes your key to ~/.microtica/credentials with owner-only permissions (0600). Delete that file to log out.

Configure with environment variables

Environment variables override the stored file, which makes them the right fit for CI and ephemeral shells:

With MICROTICA_TOKEN set, you can skip microtica login entirely:

export MICROTICA_TOKEN=mic_…
export MICROTICA_PROJECT_ID=<project-id>
microtica whoami

Set a default project

Most commands need a project id. Pass --project <id> on any command, or set MICROTICA_PROJECT_ID once so you don't repeat it. The --project flag wins when both are present.

# Per command
microtica env list --project <project-id>

# Or set it once for the session
export MICROTICA_PROJECT_ID=<project-id>
microtica env list

Run microtica project list to find the ids of the projects your key can access.

Verify your session

microtica whoami shows the identity behind your stored key and probes the API, so you can confirm both the key and that it still works:

microtica whoami

via:                apikey
api key prefix:     mic_d60bea1d
api reachable:      true
projects visible:   12

Next steps

• Run your first commands
• Control output and filter with queries