feat(init): add runok init subcommand (#152)

Co-authored-by: Claude Opus 4.6 <[email protected]>

Author: fohte

Cargo.lock

@@ -25,12 +25,14 @@ seccompiler = "=0.5.0"
 anyhow = "=1.0.102"
 cel-interpreter = "=0.10.0"
 clap = { version = "=4.5.60", features = ["derive"] }
+dialoguer = "=0.11.0"
 schemars = { version = "=1.2.1", optional = true }
 serde = { version = "=1.0.228", features = ["derive"] }
 serde-saphyr = "=0.0.20"
 serde_json = "=1.0.149"
 sha2 = "=0.10.9"
 shlex = "=1.3.0"
+similar = { version = "=2.7.0", features = ["unicode"] }
 thiserror = "=2.0.18"
 tree-sitter = "=0.26.5"
 tree-sitter-bash = "=0.25.1"

Cargo.toml

@@ -140,7 +140,15 @@ Pre-built binaries are also available on [GitHub Releases](https://github.com/fo
 
 ### Configure
 
-Create `~/.config/runok/runok.yml`:
+The fastest way to get started is with the interactive setup wizard:
+
+```sh
+runok init
+```
+
+This creates a `runok.yml`, and if you have Claude Code configured, migrates your Bash permissions to runok rules and registers the PreToolUse hook automatically.
+
+You can also configure manually. Create `~/.config/runok/runok.yml`:
 
 ```yaml
 rules:
@@ -155,9 +163,7 @@ defaults:
   action: ask
 ```
 
-### Integrate with Claude Code
-
-Add runok as a PreToolUse hook in `.claude/settings.json`:
+And add runok as a PreToolUse hook in `.claude/settings.json`:
 
 ```json
 {

README.md

@@ -0,0 +1,64 @@
+---
+title: runok init
+description: Initialize runok configuration with an interactive setup wizard.
+sidebar:
+  order: 4
+---
+
+`runok init` creates a `runok.yml` configuration file through an interactive setup wizard. It can also detect existing Claude Code Bash permissions and migrate them to runok rules.
+
+## Usage
+
+```sh
+runok init [options]
+```
+
+## Flags
+
+### `--scope <scope>`
+
+Configuration scope. Available values:
+
+- `user` — Create `~/.config/runok/runok.yml` for global rules that apply to all projects. Also registers the runok PreToolUse hook in `~/.claude/settings.json` if Claude Code is detected.
+- `project` — Create `runok.yml` in the current directory for project-specific rules.
+
+When omitted, the wizard prompts you to choose.
+
+### `-y`, `--yes`
+
+Accept all defaults without prompting. Useful for scripted setups.
+
+## What the wizard does
+
+1. **Scope selection** — Choose `user` or `project` scope (skipped if `--scope` is given).
+2. **Claude Code detection** — If a `.claude/settings.json` exists with Bash permissions or a missing runok hook, the wizard offers to:
+   - **Migrate Bash permissions** — Convert `permissions.allow` and `permissions.deny` entries for `Bash(...)` patterns into runok rules, and remove them from `settings.json`.
+   - **Register the hook** — Add the `runok check` PreToolUse hook to `settings.json` (user scope only).
+3. **Preview and confirm** — Show a unified diff of all proposed changes and ask for confirmation.
+4. **Create `runok.yml`** — Write the configuration file with migrated rules (if any) or a boilerplate template.
+
+## Examples
+
+Interactive setup (prompts for scope and options):
+
+```sh
+runok init
+```
+
+Set up user-global configuration non-interactively:
+
+```sh
+runok init --scope user -y
+```
+
+Set up project-local configuration:
+
+```sh
+runok init --scope project
+```
+
+## Related
+
+- [Quick Start](/getting-started/quickstart/) — Getting started with runok.
+- [Claude Code Integration](/getting-started/claude-code/) — Manual hook setup and sandbox configuration.
+- [Configuration](/configuration/schema/) — Full configuration reference.

docs/src/content/docs/cli/init.md

@@ -5,10 +5,14 @@ sidebar:
   order: 1
 ---
 
-runok provides two main subcommands for evaluating and executing commands against your permission rules.
+runok provides subcommands for initializing configuration, evaluating commands, and executing them against your permission rules.
 
 ## Commands
 
+### [`runok init`](/cli/init/)
+
+Initialize runok configuration with an interactive setup wizard. Detects existing Claude Code Bash permissions and offers to migrate them to runok rules.
+
 ### [`runok check`](/cli/check/)
 
 Evaluate a command against your rules and report the decision — without executing it. Useful for previewing what runok would do, or for integrating with external tools like [Claude Code hooks](/getting-started/claude-code/).

docs/src/content/docs/cli/overview.md

@@ -18,6 +18,10 @@ runok integrates with [Claude Code](https://docs.anthropic.com/en/docs/claude-co
 
 If you haven't already, follow the [Quick Start](/getting-started/quickstart/) to install runok and create a `runok.yml`.
 
+:::tip
+[`runok init --scope user`](/cli/init/) can automate steps 1 and 2: it creates a `runok.yml`, migrates existing Claude Code Bash permissions, and registers the hook — all in one command.
+:::
+
 ## Step 2: Configure the PreToolUse hook
 
 Add the runok hook to your Claude Code settings file (`.claude/settings.json`):