Initialize Use Case

When to use

Start a new use case from scratch
Create the initial folder structure for an n8n workflow project
Bootstrap a new automation with correct Codika patterns

Prerequisites

codika CLI installed
For project creation: authenticated via codika login (optional — scaffolding works without auth)

Command

codika init <path> [options]

Arguments

Argument	Description
`<path>`	Directory to create the use case in

Options

Option	Description	Default
`--name <name>`	Use case display name	Interactive prompt
`--description <desc>`	Use case description	Auto-generated
`--icon <icon>`	Lucide icon name	`Workflow`
`--no-project`	Skip project creation on the platform	—
`--project-id <id>`	Use existing project ID (no API call)	—
`--no-install`	Skip npm install after scaffolding	Runs npm install
`--project-file <path>`	Custom filename for the project file	`project.json`
`--api-url <url>`	Override API URL	—
`--api-key <key>`	Override API key	—
`--profile <name>`	Use a specific profile instead of the active one	—
`--json`	Output result as JSON	—

What it creates

my-use-case/
  config.ts                    # Deployment configuration with 3 template workflows
  version.json                 # Version tracking, initialized to 1.0.0
  project.json                 # Platform project ID and org ID (if project created)
  CLAUDE.md                    # Use case documentation for AI agents
  package.json                 # Dependencies (codika)
  tsconfig.json                # TypeScript config for IDE type-checking
  .gitignore                   # Ignores node_modules/
  node_modules/                # Installed automatically (unless --no-install)
  workflows/
    main-workflow.json         # HTTP-triggered parent workflow
    scheduled-report.json      # Schedule-triggered workflow (Monday 9 AM)
    text-processor.json        # Sub-workflow called by main workflow
  skills/
    main-workflow/
      SKILL.md                 # Agent skill for the HTTP workflow
    scheduled-report/
      SKILL.md                 # Agent skill for the scheduled workflow

Agent skills

The scaffold includes two agent skills — one for each triggerable workflow. Skills are Claude-compatible SKILL.md files that describe how to interact with the workflow’s endpoint. No skill is created for text-processor because sub-workflows are not directly triggerable. Skills are automatically collected and deployed when you run codika deploy use-case.

Template workflows

The scaffold generates three workflows that demonstrate different patterns:

main-workflow.json (HTTP trigger)

Webhook trigger with input validation
Codika Init (HTTP mode — extracts metadata)
Calls text-processor sub-workflow via SUBWKFL placeholder
Codika Submit Result / Report Error

scheduled-report.json (Schedule trigger)

Schedule Trigger (cron) + manual Webhook
Codika Init (schedule mode — creates execution via API)
Business logic placeholder
Codika Submit Result / Report Error

text-processor.json (Sub-workflow)

Execute Workflow Trigger (receives data from parent)
No Codika Init node
Processes data and returns result to parent

Feature	Where
HTTP trigger with input validation	`main-workflow.json`
Schedule trigger (Monday 9 AM)	`scheduled-report.json`
Manual webhook fallback	`scheduled-report.json`
Sub-workflow pattern	`text-processor.json`
SUBWKFL placeholder	`main-workflow.json` calls `text-processor`
Codika Init (HTTP mode)	`main-workflow.json`
Codika Init (schedule mode)	`scheduled-report.json`
Submit Result / Report Error	All parent workflows
Placeholder usage	All workflows

Behavior

Creates the folder structure and generates all template files
If authenticated and --no-project is not set:
- Creates a project on the Codika platform via API
- Writes projectId and organizationId to project.json
If --project-id is provided:
- Uses that ID without making an API call
- Writes to project.json
Checks if a parent directory already has codika in its package.json:
- If found (e.g., inside a monorepo): reuses the existing workspace, skips dependency setup
- If not found: creates package.json, tsconfig.json, .gitignore, and runs npm install
If --no-install is set: creates the dependency files but skips npm install

Project organization

Single use case (default)

When you scaffold a use case in a standalone directory, the CLI creates a self-contained project with its own package.json and dependencies:

codika init ./email-automation --name "Email Automation"

email-automation/
  config.ts
  version.json
  project.json
  package.json        # Own dependencies
  tsconfig.json
  .gitignore
  node_modules/       # Own copy of codika
  workflows/
    ...

This is the simplest approach — each use case is a self-contained, portable project.

Multiple use cases (shared workspace)

If you plan to manage multiple use cases in a single repository, create a shared workspace with one package.json at the root. All use cases share the same dependencies:

# 1. Set up the workspace
mkdir my-automations && cd my-automations
npm init -y
npm install codika
echo 'node_modules/' > .gitignore

# 2. Scaffold use cases inside it
codika init ./email-automation --name "Email Automation"
codika init ./report-generator --name "Report Generator"
codika init ./crm-sync --name "CRM Sync"

my-automations/
  package.json            # Shared dependencies
  node_modules/           # Single copy of codika
  email-automation/
    config.ts
    version.json
    workflows/
  report-generator/
    config.ts
    version.json
    workflows/
  crm-sync/
    config.ts
    version.json
    workflows/

The CLI automatically detects the shared package.json and skips creating per-use-case dependency files. Each use case is still independently deployable — codika deploy use-case ./email-automation works regardless of the project structure. This is the recommended approach when you have multiple use cases, since it avoids duplicating node_modules and keeps everything in one place.

Examples

# Interactive scaffold with auto project creation
codika init ./email-automation --name "Email Automation"

# Scaffold without creating a platform project
codika init ./local-test --name "Local Test" --no-project

# Scaffold with an existing project ID
codika init ./my-tool --name "My Tool" --project-id abc123

# Non-interactive, full options
codika init ./crm-sync \
  --name "CRM Sync" \
  --description "Syncs contacts between CRM and email" \
  --icon "RefreshCw"

Next steps after init

# Verify the scaffold is valid
codika verify use-case ./my-use-case

# Deploy to the platform
codika deploy use-case ./my-use-case

If you used --no-project, create a project before deploying:

codika project create --name "My Automation" --path ./my-use-case

Exit codes

Code	Meaning
`0`	Success
`1`	Runtime error
`2`	CLI validation error (e.g., directory already exists)

Overview

Setup

Build

Deploy

Operate

When to use

Prerequisites

Command

Arguments

Options

What it creates

Agent skills

Template workflows

main-workflow.json (HTTP trigger)

scheduled-report.json (Schedule trigger)

text-processor.json (Sub-workflow)

Behavior

Project organization

Single use case (default)

Multiple use cases (shared workspace)

Examples

Next steps after init

Exit codes

​When to use

​Prerequisites

​Command

​Arguments

​Options

​What it creates

​Agent skills

​Template workflows

​main-workflow.json (HTTP trigger)

​scheduled-report.json (Schedule trigger)

​text-processor.json (Sub-workflow)

​Behavior

​Project organization

​Single use case (default)

​Multiple use cases (shared workspace)

​Examples

​Next steps after init

​Exit codes

When to use

Prerequisites

Command

Arguments

Options

What it creates

Agent skills

Template workflows

main-workflow.json (HTTP trigger)

scheduled-report.json (Schedule trigger)

text-processor.json (Sub-workflow)

Behavior

Project organization

Single use case (default)

Multiple use cases (shared workspace)

Examples

Next steps after init

Exit codes