Skip to main content

​
Installation

npm install -g @codika-io/helper-sdk
Verify: 
codika-helper --version
The package name is @codika-io/helper-sdk. The binary is codika-helper. Requirements: Node.js 22 or higher (uses experimental strip-types).

​
Command hierarchy

codika-helper
  ├── 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
  ├── trigger <workflowId>       # Trigger a deployed workflow
  ├── get
  │   ├── use-case <projectId>   # Fetch deployed use case
  │   └── execution <executionId> # Fetch execution details
  ├── project
  │   └── create                 # Create a new project
  └── completion [shell]         # Generate shell completions

​
Configuration

Configuration is stored at ~/.config/codika-helper/config.json (XDG-compliant) with 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 in use case folder
  3. 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

​
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

​
API communication

The CLI communicates with the Codika platform API for all remote operations (deployment, triggering, project creation, etc.). Authentication is handled automatically via your stored profile — no manual endpoint configuration is needed.