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

# Initialize Use Case

> Scaffold a new use case folder with config, template workflows, agent skills, version tracking, and optional platform project creation

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

```bash theme={null}
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](/concepts/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

1. Creates the folder structure and generates all template files
2. If authenticated and `--no-project` is not set:
   * Creates a project on the Codika platform via API
   * Writes `projectId` and `organizationId` to `project.json`
3. If `--project-id` is provided:
   * Uses that ID without making an API call
   * Writes to `project.json`
4. 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`
5. 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:

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

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

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

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

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