# rok-cli

> The `rok` developer CLI — scaffolding, database management, code generation, and AI agent integration.

Part of the [Rok Framework](https://rok.rs) — a full-stack Rust web framework built on Axum 0.8 and SQLx 0.8.

[![crates.io](https://img.shields.io/crates/v/rok-cli.svg)](https://crates.io/crates/rok-cli)
[![docs.rs](https://img.shields.io/docsrs/rok-cli)](https://docs.rs/rok-cli)
[![MIT](https://img.shields.io/crates/l/rok-cli)](LICENSE)

## Features

- `rok make:*` generators — models, controllers, migrations, jobs, events, scaffolds
- `rok db:*` commands — migrate, rollback, status, fresh, pull (introspect DB to stubs)
- `rok queue:*` commands — monitor, retry, flush queues
- `rok dev` — hot-reload dev server wrapping `cargo-watch`
- `rok tui` — launch the rok-tui terminal dashboard
- `rok agent:claude` — start a Claude Code session with Rok coding conventions pre-loaded
- `rok plan:*` — navigate the implementation roadmap, print next phase, render a DOT graph
- `rok self-update` / `rok self-migrate` / `rok self-status` — CLI lifecycle management
- `--json` flag on every command for machine-readable output

## Installation

```bash
cargo install rok-cli
```

Or with `rok-tui` bundled:

```bash
cargo install rok-cli --features tui
```

## Quick Start

```bash
# Create a new Rok project
rok new my-blog

# Generate a model with migration
rok make:model Post title:String body:Text published:bool --migration

# Generate a CRUD controller
rok make:controller PostsController --resource

# Run database migrations
rok db:migrate

# Start the development server with hot reload
rok dev
```

## Code Generation

```bash
# Models and migrations
rok make:model User name:String email:String --migration
rok make:migration add_avatar_to_users

# Controllers
rok make:controller UsersController --resource    # index/show/store/update/destroy
rok make:controller AuthController               # blank controller

# Background jobs and events
rok make:job SendWelcomeEmail
rok make:event UserRegistered
rok make:listener SendWelcomeEmailListener --event UserRegistered

# Full auth scaffold (JWT + session + social login stubs)
rok make:scaffold auth

# Full billing scaffold (Stripe webhook + subscription model)
rok make:scaffold billing

# Generate a feature from a JSON spec file
rok make:feature --spec features/notifications.json
```

## Database Commands

```bash
rok db:migrate                   # apply pending migrations
rok db:rollback                  # rollback the last batch
rok db:rollback --steps 3        # rollback 3 batches
rok db:status                    # show applied / pending migrations
rok db:fresh                     # drop all tables + re-run all migrations
rok db:seed                      # run seeders
rok db:pull                      # introspect the DB and generate model stubs
```

## Queue Commands

```bash
rok queue:work                   # start processing jobs
rok queue:work --queue=critical  # process a specific queue
rok queue:monitor                # live queue depth and job stats
rok queue:retry --failed         # re-queue all failed jobs
rok queue:flush                  # delete all pending jobs (careful!)
```

## Self-Management

```bash
rok self-update                          # install the latest version
rok self-update --version 0.1.4         # install a specific version
rok self-update --dry-run               # check without installing
rok self-migrate                        # migrate config files to current format
rok self-migrate --from 0.1.0 --to 0.2.0
rok self-status                         # show installed, latest, and migration status
```

## Planning and AI Agent Integration

```bash
rok plan:next                    # print the next unimplemented phase from plan.md
rok plan:list                    # list all phases with completion status
rok plan:graph                   # emit a DOT graph for Graphviz
rok plan:status --phase 40       # detailed status for a specific phase

rok agent:rules                  # print Rok coding conventions for an AI context window
rok agent:context --phase 40     # print full context for the given phase
rok agent:claude --phase 40      # launch Claude Code with Rok system prompt + phase context
rok agent:opencode               # launch opencode with Rok context pre-loaded
```

## Developer Utilities

```bash
rok routes                       # list all registered Axum routes
rok key:generate                 # generate APP_KEY and JWT_SECRET
rok ts-client --output types/    # generate a TypeScript API client from OpenAPI spec
rok check                        # run clippy + tests + format check in one command
rok tui                          # launch the rok-tui terminal dashboard
```

## JSON Output

Every command supports `--json` / `-j`:

```bash
rok self-status --json
# {"installed":"0.2.0","latest":"0.2.1","needs_migration":false}

rok plan:list --json | jq '.[] | select(.complete == false) | .name'
rok routes --json | jq '.[] | select(.method == "POST")'
```

## License

MIT
