Operations Reference - Codika Documentation

Overview

This reference covers every operation available on the Codika platform. Each page documents the what, when, how (CLI command + all flags), and why for a single capability. Operations are grouped by lifecycle phase. The codika CLI (npm install -g codika) is the primary interface for all operations. Requires Node.js 22+.

Operations by lifecycle phase

Setup

Operation	CLI command	What it does
Authentication	`login`, `whoami`, `use`, `logout`, `config`	Install CLI, authenticate, manage profiles, switch organizations
Create Project	`project create`	Create a platform project and link it to a use case folder
Create Organization	`organization create`	Create a new organization
Create Organization Key	`organization create-key`	Create an API key for an organization
Update Organization Key	`organization update-key`	Update scopes, name, or description of an API key

Build

Operation	CLI command	What it does
Initialize Use Case	`init <path>`	Scaffold a new use case folder with template workflows and agent skills
Verify Use Case	`verify use-case`, `verify workflow`	Validate use cases against structural and semantic rules

Deploy

Operation	CLI command	What it does
Deploy Use Case	`deploy use-case <path>`	Deploy workflows to the platform with version management
Deploy Data Ingestion	`deploy process-data-ingestion <path>`	Deploy RAG/embedding pipeline configuration
Deploy Documents	`deploy documents <path>`	Upload stage documentation to the platform
Publish Use Case	`publish <templateId>`	Promote a deployment from dev to production
Rerun Deployment	`rerun deployment`	Update parameters on an existing instance without a new version

Operate

Operation	CLI command	What it does
Trigger Workflow	`trigger <workflowId>`	Execute a deployed workflow via HTTP
Fetch Use Case	`get use-case <projectId>`	Download a deployed use case from the platform
Get Execution	`get execution <executionId>`	Debug executions with node-level details
Get Instance	`get instance [instanceId]`	Inspect a live instance — parameters, status, version, workflows
Activate / Deactivate Instance	`instance activate/deactivate [instanceId]`	Activate or deactivate a process instance
List Executions	`list executions <instanceId>`	List recent executions for a process instance
List Instances	`list instances`	List all process instances for an organization
List Projects	`list projects`	List all projects for an organization
Get Project	`get project <projectId>`	Inspect project details — status, deployment, stages
Get Skills	`get skills [instanceId]`	Download agent skill documents from a deployed process
Manage Integrations	`integration set/list/delete`	Configure API keys and credentials for organizations
Status	`status [path]`	Check identity, context, and deployment readiness

CLI global configuration

Configuration is stored at ~/.config/codika/config.json (XDG-compliant, permissions 0o600). The CLI supports multiple named profiles, each containing:

Field	Description
`apiKey`	The Codika API key (prefix `cko_`)
`baseUrl`	Platform API URL
`orgId`	Organization ID
`orgName`	Organization display name
`keyName`	API key display name
`scopes`	Permission scopes (e.g., `deploy:use-case`, `workflows:trigger`)
`createdAt`	When the key was created
`expiresAt`	When the key expires

Resolution chains

The CLI resolves values in a predictable priority order. Higher-priority sources override lower ones.

API key resolution

--api-key flag (highest priority)
CODIKA_API_KEY environment variable
Active profile in config file
Error if none found

Base URL resolution

--api-url flag
CODIKA_API_URL environment variable (or per-endpoint vars like CODIKA_DEPLOY_API_URL)
Active profile base URL
Production default

Project ID resolution

--project-id flag
project.json at --project-file path (if provided)
project.json in use case folder
PROJECT_ID export in config.ts

Organization-aware profile selection

When project.json contains an organizationId, the CLI automatically selects the profile that matches that organization — even if a different profile is currently active. This is especially important for deployment commands. The selection order:

--api-key flag (always wins)
CODIKA_API_KEY environment variable
Profile matching organizationId from project.json
Active profile

Global options

These options work across most commands:

Option	Description
`--json`	Output as machine-readable JSON
`--api-key <key>`	Override API key
`--api-url <url>`	Override API base URL
`--project-file <path>`	Path to custom project file (default: `project.json`)
`--profile <name>`	Use a specific profile instead of the active one

Global exit codes

Code	Meaning
`0`	Success
`1`	Runtime error (API failure, missing files, etc.)
`2`	CLI validation error (invalid arguments, missing required options)

Profile expiry warnings

On every command, the CLI checks the active profile’s key expiry:

< 7 days until expiry: Displays a warning
Expired: Displays an error
No expiry data: No warning

Typical workflow

An agent or human orchestrating a full deployment uses operations in this order:

authentication       → Verify CLI installed and authenticated
create-project       → Create platform project (if needed)
init-use-case        → Scaffold the use case folder
(Build config.ts and workflows)
verify-use-case      → Validate before deploying
deploy-use-case      → Deploy to platform (dev)
6b. deploy-data-ingestion → Deploy DI config (if RAG use case)
6c. deploy-documents    → Upload stage documents
trigger-workflow     → Test the deployment
get-execution        → Debug if needed
list-executions      → Review recent execution history
publish-use-case    → Publish to production when ready
rerun-deployment    → Update parameters without new version
get-instance        → Inspect live instance (parameters, status, version)
instance activate   → Activate or deactivate instances
list instances      → List all process instances for the org
manage-integrations → Configure required API keys/credentials

Command hierarchy

codika
  ├── login                      # Save API key (alias for config set)
  ├── logout [name]              # Remove a profile
  ├── whoami                     # Show current identity
  ├── use [name]                 # Switch active profile or list profiles
  ├── status [path]              # Show identity and use case context
  ├── init <path>                # Scaffold a new use case
  ├── config
  │   ├── set                    # Save API key and base URL
  │   ├── show                   # Display all profiles
  │   └── clear                  # Remove configuration
  ├── verify
  │   ├── use-case <path>        # Validate entire use case folder
  │   └── workflow <path>        # Validate single workflow file
  ├── deploy
  │   ├── use-case <path>        # Deploy use case to platform
  │   ├── process-data-ingestion <path>  # Deploy data ingestion config
  │   └── documents <path>       # Upload stage documentation
  ├── publish <templateId>       # Publish deployment to production
  ├── rerun deployment           # Rerun deployment with updated parameters
  ├── integration
  │   ├── set <integrationId>    # Create or update an integration
  │   ├── list                   # List integrations and connection status
  │   └── delete <integrationId> # Delete an integration
  ├── trigger <workflowId>       # Trigger a deployed workflow
  ├── get
  │   ├── use-case <projectId>   # Fetch deployed use case
  │   ├── execution <executionId> # Fetch execution details
  │   ├── instance [instanceId]  # Inspect live instance details
  │   ├── project <projectId>    # Inspect project details
  │   └── skills [instanceId]    # Fetch agent skill documents
  ├── instance
  │   ├── activate [instanceId]   # Activate a process instance
  │   └── deactivate [instanceId] # Deactivate a process instance
  ├── list
  │   ├── executions <instanceId> # List recent executions
  │   ├── instances               # List all process instances
  │   └── projects                # List all projects
  ├── project
  │   └── create                 # Create a new project
  ├── organization
  │   ├── create                 # Create a new organization
  │   ├── create-key             # Create an organization API key
  │   └── update-key             # Update an organization API key
  └── completion [shell]         # Generate shell completions

​Overview

​Operations by lifecycle phase

​Setup

​Build

​Deploy

​Operate

​CLI global configuration

​Resolution chains

​API key resolution

​Base URL resolution

​Project ID resolution

​Organization-aware profile selection

​Global options

​Global exit codes

​Profile expiry warnings

​Typical workflow

​Command hierarchy