Commands Reference#

All Lokio commands with their options and usage examples.

lokio init##

Initialize Lokio in your project. Run once at the start.

lokio init
lokio init --enterprise <code>   # activate Enterprise at the same time

What gets created:

• lokio.yaml — project metadata
• lokio.local.yaml — API key placeholder (auto-added to .gitignore)
• lokio/configs.yaml — templates, check config, and AI config (pre-filled with defaults)
• lokio/templates/ — folder for .lokio files with an example template
• .gitignore — lokio.local.yaml is automatically added

Enterprise flag (--enterprise <code>): Creates a minimal lokio.yaml + lokio/configs.yaml without templates. Run lokio pull after this to pull templates from the Hub.

lokio doctor##

Diagnose your entire Lokio setup and display the status of each component.

lokio doctor

What gets checked:

Example output:

  Project Config
  ✓  lokio.yaml                     project: my-app v2.0.14

  Templates & Config
  ✓  lokio/configs.yaml             2 template(s)
  ✓    template: service            lokio/templates/service.lokio
  ✗    template: screen             file missing: lokio/templates/screen.lokio
  ⚠  check config                  not configured

  AI Integration
  ✓  AI config                      provider: gemini, model: gemini-2.0-flash
  ✗  AI api_key                     not set — add api_key to lokio.local.yaml

  Security
  ✓  .gitignore                     lokio.local.yaml is listed

  Lock File
  ✓  lokio.lock                     3 generation(s) tracked, all files present

Status:

• ✓ OK
• ⚠ Warning — works but needs attention
• ✗ Error — needs to be fixed
• – Skip — component not yet configured

lokio add / lokio a##

Create a new template interactively.

lokio add
lokio add service          # provide template name directly
lokio add screen --multi   # directly use multi-file mode
lokio a api -m             # alias + short flag

Flow:

1. Template name
2. Template description
3. Single-file or multi-file?
4. Output path (where generated files are saved)
5. Blueprint filename (name of the .lokio file)
6. Additional parameters (optional)

lokio edit / lokio e##

Edit an existing template's configuration (not the .lokio content, but its metadata in configs.yaml).

lokio edit service
lokio e screen

Edit options:

• Description
• Path & Output (single-file) or Files (multi-file)
• Parameters — add, edit, or delete parameters
• Convert single ↔ multi-file

To edit the template content (.lokio file), open it directly in your editor.

lokio remove / lokio rm##

Remove a template from configs.yaml.

lokio remove service
lokio rm screen

You will be asked whether the .lokio file should also be deleted.

lokio gen / lokio g##

Generate code from a template.

# Interactive — choose template, fill in all parameters one by one
lokio gen
lokio g
 
# Specify template
lokio gen service
lokio g screen
 
# Specify template + first parameter (name) at once
lokio gen service UserProfile
lokio g screen Home
 
# Re-generate a single file (update file from the latest template)
lokio gen --update src/services/UserService.ts
 
# Batch generate from a JSON file
lokio gen service --batch entities.json

Parameter collision: If your parameter name matches a built-in helper (camelCase, plural, etc.), Lokio will display a warning because the helper will be overridden.

--update <file>##

Re-generate a single file that was previously generated. Uses 3-way merge so your manual changes are not lost.

lokio gen --update src/services/UserService.ts

--batch <file>##

Generate multiple files at once from a JSON file. The JSON file must be an array of parameter objects.

lokio gen service --batch entities.json

Example entities.json:

[
  { "name": "User" },
  { "name": "Order", "type": "repository" },
  { "name": "Product" }
]

lokio diff##

Preview what will change if lokio sync is run — without writing anything.

lokio diff

Example output:

  ✓ src/services/UserService.ts — no changes
  ~ src/services/OrderService.ts — +3 -1 (your edits preserved)
  ✗ src/services/TokenService.ts — conflict (resolve markers manually)

2 changed, 1 up to date — run lokio sync to apply

lokio sync##

Apply template changes to already-generated files. Uses 3-way merge to preserve manual changes.

lokio sync

Flow:

1. Scan all files in lokio.lock
2. Re-render each file from the latest template
3. Compare with the git version (HEAD) as the merge base
4. Display a change summary
5. Ask: Apply all / Review each / Cancel

Status types:

lokio check##

Validate files in the repo against the structural rules defined in templates.

lokio check

Different from lokio diff/lokio sync: check doesn't care whether a file was generated with Lokio. It scans the entire repo and matches files based on the template output path pattern.

Rules can be defined with annotations in .lokio files:

<%# @lokio required danger "Must have @Injectable()" @Injectable %>
<%# @lokio forbidden warning "Do not use any" : any %>

Configuration in lokio/configs.yaml:

check:
  danger_mode: block   # "block" = exit code 1 (fits pre-commit hook)
                       # "warn"  = display only, no exit 1
  # templates:         # optional — omit to check all templates
  #   - service
  #   - controller

As a pre-commit hook:

# .git/hooks/pre-commit
#!/bin/sh
lokio check

lokio ai##

Validate team standards using AI. AI analyzes files in the repo and compares them against the standards you defined.

lokio ai

First-time setup (if not yet configured), an interactive wizard will appear:

⚠ AI config not found in lokio/configs.yaml.

? Set up AI config now? › Yes

◇  Select AI provider:
│  Gemini  ← free tier

◇  Model name:
│  gemini-2.0-flash

◇  Add sample standards (unit-test, no-console-log)?
│  Yes

✓  AI config written to lokio/configs.yaml
✓  Created lokio.local.yaml (gitignored)

╭─ Next step ───────────────────────────────────╮
│  Fill in your API key in lokio.local.yaml:    │
│                                               │
│    ai:                                        │
│      api_key: YOUR_KEY_HERE                   │
│                                               │
│  Then run 'lokio ai' again.                   │
╰───────────────────────────────────────────────╯

Configuration in lokio/configs.yaml (safe to commit — contains no secrets):

ai:
  provider: gemini        # openai | anthropic | gemini | ollama | openrouter
  model: gemini-2.0-flash
 
standards:
  - id: unit-test
    description: "Every service must have a unit test file"
    severity: danger      # danger | warning
  - id: no-console-log
    description: "No console.log in production code"
    severity: warning

API key in lokio.local.yaml (gitignored — do not commit):

# lokio.local.yaml
ai:
  api_key: YOUR_API_KEY_HERE

Or use an environment variable:

export LOKIO_AI_API_KEY=your-key

Supported providers:

Example output:

  ✓  unit-test               PASS  All services have corresponding test files
  ✗  no-console-log          FAIL  Found console.log in production code
       └─ src/services/UserService.ts

  ──────────────────────────────────────────────────────────
  Summary:  1 pass  /  1 fail  — 2 standard(s) checked

  ✗  Danger standards failed. Fix before merging.

lokio run##

Execute a predefined sequence of shell commands (steps) defined in lokio/configs.yaml.

lokio run --id <id>
 
# Examples
lokio run --id install-docker
lokio run --id setup-vm

Configuration in lokio/configs.yaml:

runs:
  - id: install-docker
    description: Install Docker & Docker Compose (Ubuntu/Debian)
    steps:
      - name: Update apt
        run: sudo apt update -y
      - name: Install Docker Engine
        run: sudo apt install -y docker-ce docker-ce-cli containerd.io
      - name: Verify Docker
        run: docker --version

Step fields:

Multi-line commands use the YAML block scalar (|):

- name: Add Docker GPG key
  run: |
    sudo install -m 0755 -d /etc/apt/keyrings
    curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
      | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

continue_on_error — useful when a step may fail non-fatally (e.g. container already running):

- name: Run Redis container
  run: docker run -d --name redis -p 6379:6379 redis:7-alpine
  continue_on_error: true

Example output:

  Running: install-docker

  ● Update apt
  ✓ Update apt

  ● Install Docker Engine
  ✓ Install Docker Engine

  ● Verify Docker
  ✓ Verify Docker

  ✓ Done — 3 step(s) completed

lokio pull##

Pull templates from the Enterprise Hub (requires Enterprise activation).

lokio pull

lokio --help##

Display a list of all commands.

lokio --help
lokio gen --help   # help for a specific command

lokio --version / lokio -V##

Display the installed Lokio version.

lokio -V