Skip to main content

​
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

OperationCLI commandWhat it does
Authenticationlogin, whoami, use, logout, configInstall CLI, authenticate, manage profiles, switch organizations
Create Projectproject createCreate a platform project and link it to a use case folder
Create Organizationorganization createCreate a new organization
Create Organization Keyorganization create-keyCreate an API key for an organization
Update Organization Keyorganization update-keyUpdate scopes, name, or description of an API key

​
Build

OperationCLI commandWhat it does
Initialize Use Caseinit <path>Scaffold a new use case folder with template workflows and agent skills
Verify Use Caseverify use-case, verify workflowValidate use cases against structural and semantic rules

​
Deploy

OperationCLI commandWhat it does
Deploy Use Casedeploy use-case <path>Deploy workflows to the platform with version management
Deploy Data Ingestiondeploy process-data-ingestion <path>Deploy RAG/embedding pipeline configuration
Deploy Documentsdeploy documents <path>Upload stage documentation to the platform
Publish Use Casepublish <templateId>Promote a deployment from dev to production
Redeploy Use CaseredeployUpdate parameters on an existing instance without a new version

​
Operate

OperationCLI commandWhat it does
Trigger Workflowtrigger <workflowId>Execute a deployed workflow via HTTP
Fetch Use Caseget use-case <projectId>Download a deployed use case from the platform
Get Executionget execution <executionId>Debug executions with node-level details
Get Instanceget instance [instanceId]Inspect a live instance — parameters, status, version, workflows
Activate / Deactivate Instanceinstance activate/deactivate [instanceId]Activate or deactivate a process instance
List Executionslist executions <instanceId>List recent executions for a process instance
List Instanceslist instancesList all process instances for an organization
List Projectslist projectsList all projects for an organization
Get Projectget project <projectId>Inspect project details — status, deployment, stages
Get Skillsget skills [instanceId]Download agent skill documents from a deployed process
Manage Integrationsintegration set/list/deleteConfigure API keys and credentials for organizations
Statusstatus [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:
FieldDescription
apiKeyThe Codika API key (prefix cko_)
baseUrlPlatform API URL
orgIdOrganization ID
orgNameOrganization display name
keyNameAPI key display name
scopesPermission scopes (e.g., deploy:use-case, workflows:trigger)
createdAtWhen the key was created
expiresAtWhen the key expires

​
Resolution chains

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

​
API key resolution

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

​
Base URL resolution

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

​
Project ID resolution

  1. --project-id flag
  2. project.json at --project-file path (if provided)
  3. project.json in use case folder
  4. 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:
  1. --api-key flag (always wins)
  2. CODIKA_API_KEY environment variable
  3. Profile matching organizationId from project.json
  4. Active profile

​
Global options

These options work across most commands:
OptionDescription
--jsonOutput 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

CodeMeaning
0Success
1Runtime error (API failure, missing files, etc.)
2CLI 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: 
1. authentication       → Verify CLI installed and authenticated
2. create-project       → Create platform project (if needed)
3. init-use-case        → Scaffold the use case folder
4. (Build config.ts and workflows)
5. verify-use-case      → Validate before deploying
6. deploy-use-case      → Deploy to platform (dev)
6b. deploy-data-ingestion → Deploy DI config (if RAG use case)
6c. deploy-documents    → Upload stage documents
7. trigger-workflow     → Test the deployment
8. get-execution        → Debug if needed
9. list-executions      → Review recent execution history
10. publish-use-case    → Publish to production when ready
11. redeploy-use-case   → Update parameters without new version
12. get-instance        → Inspect live instance (parameters, status, version)
13. instance activate   → Activate or deactivate instances
14. list instances      → List all process instances for the org
15. 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
  ├── redeploy                   # Redeploy instance 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