Skip to main content

​
Prerequisites

  • Node.js 22 or higher
  • npm
  • A Codika API key (obtain from the Codika dashboard under Organization Settings > API Keys)

​
Step 1: Install the CLI

npm install -g @codika-io/helper-sdk
Verify the installation: 
codika-helper --version

​
Step 2: Authenticate

codika-helper login
This prompts for your API key (masked input), verifies it against the platform, and stores a named profile in ~/.config/codika-helper/config.json. For non-interactive environments: 
codika-helper login --api-key cko_your_api_key_here
Verify your identity: 
codika-helper whoami
Output: 
Organization:  My Company
Key name:      dev-key
Key:           cko_abc...xyz
Scopes:        deploy:use-case, workflows:trigger
Expires:       2026-12-31
Profile:       my-company

​
Step 3: Scaffold a use case

codika-helper init my-first-automation --name "My First Automation"
This creates: 
my-first-automation/
  config.ts                    # Deployment configuration
  version.json                 # Version tracking (starts at 1.0.0)
  project.json                 # Platform project ID
  workflows/
    main-workflow.json         # HTTP-triggered parent workflow
    scheduled-report.json      # Schedule-triggered workflow
    text-processor.json        # Sub-workflow (called by parent)
The template includes three workflows demonstrating different trigger types (HTTP, schedule, sub-workflow), the mandatory Codika node pattern, and placeholder usage.

​
Step 4: Validate

codika-helper verify use-case ./my-first-automation
Expected output if valid: 
✓ Use case validation passed
  must: 0  should: 0  nit: 0
If there are issues, the CLI lists each finding with rule ID, severity, file, and message. Use --fix to auto-fix what it can: 
codika-helper verify use-case ./my-first-automation --fix

​
Step 5: Deploy

codika-helper deploy use-case ./my-first-automation
The CLI:
  1. Reads version.json (1.0.0)
  2. Bumps to 1.0.1 (patch by default)
  3. Packages all workflow files
  4. Sends to the Codika platform API
  5. On success: updates version.json, archives deployment locally, saves devProcessInstanceId to project.json
Output: 
✓ Deployed successfully
  Version:     1.0.1 (API: 1.1)
  Workflows:   3
  Project:     abc123
  Instance:    def456

​
Step 6: Trigger a workflow

codika-helper trigger main-workflow --poll --payload-file - <<'EOF'
{"message": "Hello world"}
EOF
The --poll flag waits for execution to complete (default timeout: 120 seconds) and prints the result.

​
Step 7: Check execution details

If you need to debug: 
codika-helper get execution <executionId> --deep --slim
The --deep flag fetches sub-workflow executions recursively. The --slim flag strips noise for readability.

​
What’s next

Core concepts

Learn how use cases, processes, and workflows relate.

Build your own

Step-by-step guide to building a custom use case from scratch.

CLI reference

Complete reference for all CLI commands and options.

Validation rules

Understand all validation rules enforced by the CLI.