Authentication

Agents / terminal-only setups: if you have email access but no browser, use the CLI OTP auth flow — two commands per signup or login, and a cko_ key lands in ~/.config/codika/config.json automatically. This page covers dashboard-paste login and profile management.

When to use

First-time environment setup (with a key already minted from the dashboard)
When deploy or project commands fail with “API key is required”
To check current identity or switch between organizations
When the user needs to authenticate with a different org
For OTP-based self-provisioning from an AI agent, see CLI OTP auth first

Prerequisites

Node.js 22+ installed
npm available

Install the CLI

# Install globally
npm install -g codika

# Verify installation
codika --version

Save an API key and create a named profile. Alias for config set.

codika login [options]

Options

Option	Description
`--api-key <key>`	API key (skips interactive prompt)
`--base-url <url>`	Base URL override (defaults to production)
`--name <name>`	Custom profile name (auto-derived from org name if omitted)
`--skip-verify`	Save without verifying the key against the API

Behavior

Prompts for API key (masked input) unless --api-key is provided
Validates the key against the Codika platform API (unless --skip-verify)
Stores profile metadata: org ID, org name, key name, scopes, creation date, expiry date
Sets the new profile as active

Examples

# Interactive login
codika login

# Non-interactive login
codika login --api-key cko_abc123def456

# Login with custom profile name
codika login --api-key cko_abc123def456 --name staging

# Login to a custom environment
codika login --api-key cko_abc123def456 --base-url https://custom.api.example.com

whoami

Show the current authenticated identity.

codika whoami [options]

Options

Option	Description
`--json`	Output as JSON

Behavior

Validates against the platform API for fresh data. Falls back to cached profile data if the network call fails.

Output

Organization:  Acme Corp
Key name:      production-key
Key:           cko_abc...xyz
Scopes:        deploy:use-case, workflows:trigger
Expires:       2026-12-31
Profile:       acme-corp

use

Switch the active profile or list all profiles.

codika use [name]

Arguments

Argument	Description
`[name]`	Profile name to switch to (optional — lists profiles if omitted)

Options

Option	Description
`--json`	Output machine-readable JSON with profile details

Behavior

No argument: Lists all profiles with an active marker (bullet)
With argument: Switches the active profile

Output (list mode)

  ● acme-corp      (Acme Corp)
    staging         (Acme Corp - Staging)
    other-org       (Other Organization)

JSON output

When called with --json, outputs an array of profile objects — useful for agents to match project.json organizationId to the correct profile:

codika use --json

[
  {
    "name": "acme-corp",
    "organizationId": "org_abc123",
    "organizationName": "Acme Corp",
    "scopes": ["deploy:use-case", "workflows:trigger"],
    "keyPrefix": "cko_abc",
    "active": true
  },
  {
    "name": "staging",
    "organizationId": "org_abc123",
    "organizationName": "Acme Corp - Staging",
    "scopes": ["deploy:use-case"],
    "keyPrefix": "cko_def",
    "active": false
  }
]

Examples

# List all profiles
codika use

# Switch to a specific profile
codika use staging

logout

Remove a profile.

codika logout [name]

Arguments

Argument	Description
`[name]`	Profile name to remove (defaults to active profile)

Behavior

Removes the specified profile. If it was the active profile, switches to the next available profile.

config set

Save API key and base URL. Same as login.

codika config set [options]

Options are identical to login.

config show

Display all stored profiles.

codika config show

Output

Profiles:
  ● acme-corp       cko_abc...xyz  (Acme Corp)
    staging          cko_def...uvw  (Acme Corp - Staging)

Exit code 0 if profiles exist, 1 if none.

config clear

Remove configuration.

codika config clear [options]

Options

Option	Description
`--profile <name>`	Remove only this profile (clears all if omitted)

Examples

# Clear a specific profile
codika config clear --profile staging

# Clear all profiles and configuration
codika config clear

Configuration storage

Item	Location
Config file	`~/.config/codika/config.json`
Permissions	`0o600` (owner read/write only)
Format	Multi-profile JSON with active profile pointer

API key resolution priority

--api-key / --api-url flag on any command
CODIKA_API_KEY / CODIKA_BASE_URL environment variable
Active profile in config file
Production default (base URL only)

Organization-aware profile selection

When project.json in a use case folder contains an organizationId, the CLI automatically selects the matching profile for deployment commands — even if a different profile is currently active.

Error reference

Error	Cause	Fix
”API key is required”	No key provided or found	Run `codika login`
”Invalid API key”	Key is wrong or expired	Check with `codika whoami`, re-login
”EACCES” on npm install	Permission denied	Use `sudo npm install -g` or fix npm permissions
Wrong org on deploy	Active profile doesn’t match project	Use `codika use <correct-profile>`

Overview

Setup

Build

Deploy

Operate

When to use

Prerequisites

Install the CLI

Options

Behavior

Examples

whoami

Options

Behavior

Output

use

Arguments

Options

Behavior

Output (list mode)

JSON output

Examples

logout

Arguments

Behavior

config set

config show

Output

config clear

Options

Examples

Configuration storage

API key resolution priority

Organization-aware profile selection

Error reference

​When to use

​Prerequisites

​Install the CLI

​login

​Options

​Behavior

​Examples

​whoami

​Options

​Behavior

​Output

​use

​Arguments

​Options

​Behavior

​Output (list mode)

​JSON output

​Examples

​logout

​Arguments

​Behavior

​config set

​config show

​Output

​config clear

​Options

​Examples

​Configuration storage

​API key resolution priority

​Organization-aware profile selection

​Error reference

When to use

Prerequisites

Install the CLI

login

Options

Behavior

Examples

whoami

Options

Behavior

Output

use

Arguments

Options

Behavior

Output (list mode)

JSON output

Examples

logout

Arguments

Behavior

config set

config show

Output

config clear

Options

Examples

Configuration storage

API key resolution priority

Organization-aware profile selection

Error reference