Getting Started#

What is Lokio?##

Lokio is a CLI for building code generators from your own templates. Instead of copy-pasting old files every time you create a new service or component, you define a template once — then generate as many times as you want with a single command.

Great for:

• Teams with a consistent folder/file structure
• Projects with lots of repetitive boilerplate (services, controllers, screens, etc.)
• Onboarding new developers so they immediately follow team conventions

Installation##

# Using bun
bun install -g lokio
 
# Using npm
npm install -g lokio
 
# Verify installation
lokio --version

Initialize a Project##

Run this command in your project's root folder:

lokio init

Follow the prompts:

◇  Select your primary language:
│  TypeScript

◇  Enable Enterprise feature?
│  No

✓ Project initialized

  Files created ✓
  - lokio.yaml
  - .gitignore (lokio.local.yaml added)
  - lokio/configs.yaml
  - lokio/templates/component.lokio

Run 'lokio gen' to generate code from templates.

After completion, the following structure will be created:

your-project/
├── lokio.yaml              ← project metadata
├── lokio.local.yaml        ← API key (auto-gitignored — do not commit!)
├── lokio.lock              ← tracking for generated files (commit this!)
└── lokio/
    ├── configs.yaml        ← all config: templates, check, ai, standards
    └── templates/
        └── component.lokio ← first example template

Contents of lokio/configs.yaml after init##

This file already contains a complete configuration — no manual setup required:

templates:
  - name: component
    description: TypeScript component
    path: component.lokio
    output: src/components/<%= fileNameCase(name) %>.tsx
    parameters:
      - name: name
        type: string
        required: true
        prompt: Name
 
# ─── Lokio Check ──────────────────────────────────────────────────────────────
check:
  danger_mode: block
 
# ─── AI Standards Check ────────────────────────────────────────────────────────
# Add your API key in lokio.local.yaml (already gitignored):
#   ai:
#     api_key: YOUR_KEY_HERE
#
ai:
  provider: gemini
  model: gemini-2.0-flash
 
standards:
  - id: unit-test
    description: "Every service must have a unit test file"
    severity: danger
  - id: no-console-log
    description: "No console.log in production code"
    severity: warning

Creating Your First Template##

lokio add

Example dialog:

◇  Template name:
│  service

◇  What does this template generate?
│  REST API service class

◇  Does this template generate more than one file at a time?
│  No

╭─ How it works ─────────────────────╮
│  Use <%= name %> in the output path │
│  to insert the user's input.        │
│  e.g. src/services/<%= name %>.ts   │
│       → src/services/UserService.ts │
╰─────────────────────────────────────╯

◇  Where should the generated file be saved?
│  src/services/<%= name %>Service.ts

◇  Blueprint filename:
│  service.lokio

◇  Add extra input variables besides 'name'?
│  No

✓  Template ready! Run 'lokio g service' to generate code from it.

Open lokio/templates/service.lokio and fill it with the structure you want:

// lokio/templates/service.lokio
 
import { Injectable } from '@nestjs/common';
 
@Injectable()
export class <%= pascalCase(name) %>Service {
  async findAll() {
    return [];
  }
 
  async findOne(id: number) {
    return { id };
  }
}

Generate Code##

lokio gen

Or directly:

lokio g service User

Result: the file src/services/UserService.ts is automatically created with the contents:

import { Injectable } from '@nestjs/common';
 
@Injectable()
export class UserService {
  async findAll() {
    return [];
  }
 
  async findOne(id: number) {
    return { id };
  }
}

Check Setup with lokio doctor##

After init, run this to make sure everything is working correctly:

lokio doctor

Example output:

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

  Templates & Config
  ✓  lokio/configs.yaml             1 template(s)
  ✓    template: component          lokio/templates/component.lokio
  ✓  check config                   danger_mode: block

  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                     no lock file yet

Typical Workflow##

1. lokio init          → one-time setup at project start
2. lokio doctor        → verify setup is correct
3. lokio add           → create a new template
4. Edit .lokio file    → fill with your team's code structure
5. lokio g [template]  → generate as many times as needed
6. lokio check         → validate files match template structure
7. lokio ai            → validate team standards with AI
8. lokio sync          → update old files when templates change

Next Steps##

• Template Syntax → — how to use variables, conditions, loops
• Parameters → — how to create richer inputs
• Commands → — reference for all commands
• Advanced Features → — multi-file, hooks, AI check, sync
• Examples → — real-world React, Go, Flutter examples, etc.