> ## Documentation Index
> Fetch the complete documentation index at: https://doc.codika.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get started in 7 steps — install codika, authenticate, scaffold a use case, validate, deploy, trigger, and debug

## 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

```bash theme={null}
npm install -g codika
```

Verify the installation:

```bash theme={null}
codika --version
```

## Step 2: Authenticate

```bash theme={null}
codika login
```

This prompts for your API key (masked input), verifies it against the platform, and stores a named profile in `~/.config/codika/config.json`.

For non-interactive environments:

```bash theme={null}
codika login --api-key cko_your_api_key_here
```

Verify your identity:

```bash theme={null}
codika 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

```bash theme={null}
codika 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
  package.json                 # Dependencies (codika)
  tsconfig.json                # TypeScript config for IDE support
  .gitignore                   # Ignores node_modules/
  node_modules/                # Dependencies installed automatically
  workflows/
    main-workflow.json         # HTTP-triggered parent workflow
    scheduled-report.json      # Schedule-triggered workflow
    text-processor.json        # Sub-workflow (called by parent)
  skills/
    main-workflow/SKILL.md     # Agent skill for the HTTP workflow
    scheduled-report/SKILL.md  # Agent skill for the scheduled workflow
```

The template includes three workflows demonstrating different trigger types (HTTP, schedule, sub-workflow), the mandatory Codika node pattern, and placeholder usage. It also includes two [agent skills](/concepts/agent-skills) that describe how AI agents can interact with the triggerable workflows. Dependencies are installed automatically so the use case is immediately deployable.

## Step 4: Validate

```bash theme={null}
codika 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:

```bash theme={null}
codika verify use-case ./my-first-automation --fix
```

## Step 5: Deploy

```bash theme={null}
codika 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 and collects agent skills from `skills/`
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

```bash theme={null}
codika 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:

```bash theme={null}
codika get execution <executionId> --deep --slim
```

The `--deep` flag fetches sub-workflow executions recursively. The `--slim` flag strips noise for readability.

## Optional: Publish to production

Once you're happy with your dev deployment, publish it to production:

```bash theme={null}
codika publish <templateId>
```

The `templateId` is stored in `project.json` under the `deployments` map after each deploy. Check it with:

```bash theme={null}
cat project.json | grep templateId
```

This creates a production process instance. See [publish](/operations/publish-use-case) for visibility and sharing options.

## Optional: Download skills for agents

Your use case already includes agent skills (created during `init`). After deploying, agents can download them:

```bash theme={null}
codika get skills
```

Or download directly into a Claude Code project:

```bash theme={null}
codika get skills --output .claude/skills
```

Any compatible coding agent (Claude Code, Cursor, …) auto-discovers the skills and knows how to trigger your workflows. See [Agent Skills](/concepts/agent-skills) for the full story.

## What's next

<CardGroup cols={2}>
  <Card title="Agent plugin" icon="plug" href="/guides/claude-code-plugin">
    Install the Codika plugin in Claude Code, Cursor, or any Open-Plugin host so agents can run these commands for you (`npx plugins add codika-io/plugin`).
  </Card>

  <Card title="Core concepts" icon="lightbulb" href="/concepts/use-cases">
    Learn how use cases, processes, and workflows relate.
  </Card>

  <Card title="Build your own" icon="hammer" href="/guides/first-use-case">
    Step-by-step guide to building a custom use case from scratch.
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/operations/overview">
    Complete reference for all CLI commands and options.
  </Card>

  <Card title="Validation rules" icon="check" href="/operations/verify-use-case">
    Understand all validation rules enforced by the CLI.
  </Card>

  <Card title="Builder System" icon="wand-magic-sparkles" href="/builder/overview">
    Let AI agents build use cases from your business requirements.
  </Card>
</CardGroup>