rok - Run One, Know All

Execute multi-step tasks from JSON - the ultimate automation tool for developers and AI agents.

What is rok?

rok is a CLI tool that executes multi-step tasks defined in JSON format. It's designed for:

• Developer workflows - Automate repetitive tasks
• AI agents - Self-contained task execution
• CI/CD pipelines - Complex build and deployment scripts
• Self-evolution - Use rok to improve rok

Installation

# From crates.io
cargo install rok-cli

# From source
git clone https://github.com/ateeq1999/rok
cd rok
cargo install --path .

# Local development
cargo install --path . --force

Quick Start

Basic Usage

# Run from file
rok -f task.json

# Run from stdin
echo '{"steps":[{"type":"bash","cmd":"echo hello"}]}' | rok

# Run from inline JSON
rok -j '{"steps":[{"type":"bash","cmd":"echo hello"}]}'

Example: File Operations

{
  "steps": [
    { "type": "mkdir", "path": "src/components" },
    { "type": "write", "path": "src/components/Hello.tsx", "content": "export const Hello = () => <div>Hello World</div>" },
    { "type": "bash", "cmd": "npm run build" }
  ]
}

Core Concepts

Steps

rok provides 20+ built-in step types:

References

Pass data between steps using refs:

{
  "steps": [
    { "type": "scan", "path": "./src", "depth": 2 },
    { "type": "each", "over": {"ref": 0, "pick": "tree.*"}, "step": { "type": "bash", "cmd": "echo {{item}}" }}
  ]
}

Conditionals

{
  "steps": [
    { "type": "grep", "pattern": "TODO", "path": "./src" },
    {
      "type": "if",
      "condition": { "type": "grep_has_results", "ref": 0 },
      "then": [
        { "type": "bash", "cmd": "echo Found TODOs!" }
      ]
    }
  ]
}

Advanced Features

Templates

Create reusable templates:

rok init-template my-component

Templates support:

• Custom props with validation
• Inheritance (extends field)
• Derived transforms (pluralize, camelcase, etc.)

Task Files

Save and reuse tasks:

# Save current payload as a named task
rok -f task.json save my-task -d "Build the project"

# Run saved task
rok run my-task

# List all tasks
rok list

Environment Variables

Use {{env.VAR_NAME}} in any string field:

{
  "steps": [
    { "type": "bash", "cmd": "echo {{env.USER}}" }
  ]
}

Timeouts & Retries

{
  "steps": [
    {
      "type": "bash",
      "cmd": "make build",
      "timeout_ms": 60000,
      "retry": {
        "count": 3,
        "delay_ms": 2000,
        "backoff": true
      }
    }
  ]
}

Step Enhancements

All steps support:

• id - Referenceable identifier
• Custom fields per step type (max_bytes, create_dirs, case_sensitive, context_lines, encoding)

CLI Commands

rok - AI Agent Task Runner

Commands:
  templates          List available templates
  init-template      Create a new template
  validate-template  Validate a template schema
  run                Run a saved task
  save               Save current payload as task
  list               List saved tasks
  edit               Edit a saved task
  watch              Watch files and re-run
  history            Show execution history
  replay             Replay a previous run

Options:
  -f, --file FILE    Path to JSON file
  -j, --json JSON    Inline JSON payload
  -o, --output       Output format: json, pretty, silent
  -v, --verbose      Enable verbose output
  -q, --quiet        Suppress output
  --dry-run          Preview without executing

Configuration

Options

{
  "name": "my-task",
  "description": "Build and deploy",
  "version": "1.0.0",
  "options": {
    "cwd": ".",
    "stop_on_error": true,
    "timeout_ms": 30000,
    "env": { "NODE_ENV": "production" }
  },
  "props": {
    "version": "1.0.0"
  },
  "steps": []
}

Self-Evolution

rok is self-hosting - use it to improve itself:

# Generate a new step module
rok -f - <<'EOF'
{
  "steps": [
    { "type": "template", "builtin": "rust-module", "output": "./src/steps/new_step.rs", "vars": { "name": "new_step" } }
  ]
}
EOF

See usage.md for more self-evolution patterns.

Development

# Build
cargo build --release

# Test
cargo test

# Lint
cargo clippy -- -D warnings

# Format
cargo fmt

License

MIT License - see LICENSE for details.