Kror CLI

Generate production-ready SwiftUI apps from plain-English prompts. One command, one compiling .xcodeproj.

System Requirements

Requirement	Minimum
macOS	13.0 (Ventura)
Xcode	14.3+ (with command line tools)
Swift	5.8+
iOS target	16.4
Node.js	20+
Ruby	System Ruby or Homebrew

Prerequisites

Before using Kror, make sure these are installed:

# 1. Xcode command line tools (if not already)
xcode-select --install

# 2. xcodeproj Ruby gem
gem install xcodeproj

# 3. Docker Desktop (for local Supabase)
# Download from https://docs.docker.com/desktop/install/mac-install/
# Note: Supabase CLI is installed per-project automatically by kror generate

# 4. Verify everything
xcode-select -p        # should print a path
ruby --version          # should print 2.x or 3.x
gem list xcodeproj      # should show xcodeproj in the list
swift --version         # should print Swift 5.8+
docker --version        # should print Docker version

You'll need an LLM API key — either from OpenRouter (default) or Anthropic.

Install

# Clone and build
cd kror-cli
npm install
npm run build

# Link globally (makes `kror` available in any terminal)
npm link

After linking, verify it works:

kror --help

Quick Start

1. Configure API keys (one-time setup)

kror init

You'll be prompted for:

• LLM provider — openrouter (default) or anthropic
• API key — your OpenRouter or Anthropic key
• LLM model — defaults to anthropic/claude-sonnet-4 (can use any model on OpenRouter)
• Local Supabase — Y (default) uses local Docker-based Supabase, n prompts for remote URL/key
• Apple Team ID — your 10-character Apple Developer Team ID
• RevenueCat API key — appl_... (or placeholder)

This creates:

• .env — API keys and LLM config (git-ignored, never committed)
• ~/.kror/config.json — non-secret project config

Manual .env setup (alternative to kror init)

Copy .env.example to .env and fill in your values:

cp .env.example .env

LLM_PROVIDER=openrouter
LLM_MODEL=anthropic/claude-sonnet-4
OPENROUTER_API_KEY=sk-or-v1-...
# ANTHROPIC_API_KEY=sk-ant-...    # uncomment if using anthropic provider
APPLE_TEAM_ID=YOUR_TEAM_ID
SUPABASE_LOCAL=true                # set to false + fill URL/key for remote
# SUPABASE_URL=https://xxx.supabase.co
# SUPABASE_ANON_KEY=eyJ...
REVENUECAT_API_KEY=appl_...

2. Generate an app

kror generate "A habit tracker app called HabitForge with onboarding and paywall"

This will:

1. Run preflight checks (Xcode, Ruby, xcodeproj)
2. Initialize local Supabase (supabase init + seed migrations)
3. Call the Planner LLM to create a task graph
4. Execute each task (create project → write code → add SPM packages → build)
5. Stream xcodebuild output to your terminal
6. Print a summary with all files written

Override the model for a single run:

kror generate "habit tracker" --model google/gemini-2.5-flash
kror generate "habit tracker" --output ~/Projects/HabitForge

3. Open in Xcode

open HabitForge/HabitForge.xcodeproj

LLM Providers

Kror supports multiple LLM providers via a pluggable abstraction.

Provider	Env var for key	Default model	Notes
openrouter (default)	OPENROUTER_API_KEY	anthropic/claude-sonnet-4	Access to 200+ models via one key
anthropic	ANTHROPIC_API_KEY	anthropic/claude-sonnet-4	Direct Anthropic API
openai	OPENAI_API_KEY	gpt-4o	Direct OpenAI API

Switch providers by changing LLM_PROVIDER in .env. Models follow OpenRouter naming (e.g. anthropic/claude-sonnet-4, google/gemini-2.5-flash).

Local Supabase (Default)

Kror defaults to a local Supabase instance powered by Docker. No remote account needed for development.

How it works

When you run kror generate, Kror automatically:

1. Installs supabase as a local devDependency in the generated project
2. Runs npx supabase init to create the supabase/ config folder
3. Creates seed migrations in supabase/migrations/ with table schemas (habits, user_profiles, etc.)
4. Configures the generated Swift code to connect to http://127.0.0.1:54321

Starting the local stack

After generating your app:

cd YourApp
npx supabase start      # starts Postgres, Auth, Storage, etc. in Docker

Local services:

Service	URL
API	http://127.0.0.1:54321
Studio (DB GUI)	http://127.0.0.1:54323
Database	postgresql://postgres:postgres@127.0.0.1:54322/postgres

Apply the seed migrations:

npx supabase db reset   # applies migrations and seeds the database

Switching to remote Supabase (production)

Set SUPABASE_LOCAL=false in .env and provide your remote credentials:

SUPABASE_LOCAL=false
SUPABASE_URL=https://YOUR_REF.supabase.co
SUPABASE_ANON_KEY=eyJ...

Then update Config.swift in your generated app with the new URL and key.

All Commands

Command	Description
kror init	One-time setup — creates .env and ~/.kror/config.json
kror generate <prompt>	Generate a full iOS app from a plain-English description
kror add <prompt> -p <dir>	Add a feature to an existing Kror project
kror build -p <dir>	Re-run just the Xcode build step
kror status -p <dir>	Print current project state (features, build status)

Options

kror generate "my app" --output ~/Projects/MyApp   # custom output dir
kror generate "my app" --model openai/gpt-4o       # use a different model
kror build --project ./MyApp                        # specify project dir
kror add "Add settings screen" --project ./MyApp    # add feature

How It Works

kror generate "habit tracker with onboarding and paywall"
        │
        ▼
  Preflight checks (Xcode, Ruby, xcodeproj gem)
        │
        ▼
  Planner (1 LLM call) → TaskGraph JSON
        │
        ▼
  Executor runs tasks sequentially:
    [1/8] xcode_builder / create_project     → .xcodeproj
    [2/8] code_writer / write_config          → Config.swift
    [3/8] code_writer / write_models          → Habit.swift, UserProfile.swift
    [4/8] code_writer / write_network_layer   → APIClient.swift, AuthManager.swift
    [5/8] code_writer / write_feature_views   → OnboardingView + ViewModel
    [6/8] code_writer / write_feature_views   → HabitsListView + ViewModel
    [7/8] xcode_builder / add_spm_packages    → supabase-swift, purchases-ios
    [8/8] xcode_builder / build_and_verify    → xcodebuild for iOS Simulator
        │
        ▼
  If build fails → auto-fix (1 LLM call to patch) → retry build once
        │
        ▼
  ✔ Done — open .xcodeproj in Xcode

Project Structure

src/
├── index.ts            ← CLI entry point (commander)
├── types.ts            ← ProjectState, Task, TaskGraph, ToolResult
├── agent/
│   ├── planner.ts      ← LLM call → task graph
│   ├── executor.ts     ← sequential task runner + auto-fix
│   └── context.ts      ← project_state.json read/write
├── llm/
│   ├── types.ts        ← LLMClient interface, provider types
│   ├── openrouter.ts   ← OpenRouter provider (OpenAI-compatible)
│   ├── anthropic.ts    ← Anthropic provider
│   └── index.ts        ← createLLMClient() factory
├── tools/
│   ├── codeWriter.ts   ← LLM → Swift files
│   ├── xcodeBuilder.ts ← Xcode project creation + build
│   └── prompts.ts      ← per-action prompt functions
└── scripts/
    ├── create_project.rb   ← xcodeproj gem: create .xcodeproj
    └── add_spm_packages.rb ← xcodeproj gem: add SPM dependencies

Development

npm run dev      # TypeScript watch mode (recompiles on save)
npm run build    # one-time TypeScript compile
npm test         # run unit tests (vitest)

Running without npm link

npm run build && node dist/index.js generate "my app"

Troubleshooting

Problem	Fix
OPENROUTER_API_KEY not set	Create .env with your key, or run kror init
Config not found	Run kror init first
xcodeproj gem missing	gem install xcodeproj
Xcode command line tools not found	xcode-select --install
Build failed	Auto-fix runs once automatically. If it still fails, check the error output and fix manually.
Planning failed	Check your API key in .env and verify the model name
Ruby script failed	Make sure ruby --version works and gem list xcodeproj shows it installed

License

MIT