roba 0.2.0

Single-prompt CLI runner built on claude-wrapper
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

# roba

**For humans** -- a binary convenience wrapper around `claude -p`:
composable input, structured output, profiles, history, cost
tracking. One invocation, one answer, done.

**For agents** in [Claude Code](https://github.com/anthropics/claude-code)
-- a stable scripting ABI: typed exit codes, versioned `--json`
envelope, `--trace` observability handle, `--no-retry` for
deterministic-on-failure runs. Bring your own skills and agents via
`~/.claude/`.

Built on [`claude-wrapper`](https://crates.io/crates/claude-wrapper).

```bash
$ roba "summarize the rust ownership model in 3 bullets"
   Rust's ownership model rests on three rules:

     • Each value has a single owner.
     • When the owner goes out of scope, the value is dropped.
     • Borrows are either many immutable or one mutable.

tokens 1.2k/450 . 2.0s . session abc12345
```

## Install

```bash
cargo install roba
```

`roba` shells out to the `claude` binary, so you need
[claude-code](https://github.com/anthropics/claude-code) installed
and authenticated on your PATH.

**Docs:** full reference and topic guides at
[joshrotenberg.github.io/roba](https://joshrotenberg.github.io/roba/).

## What it does that `claude -p` doesn't

| | |
|---|---|
| **Prompt sources** | positional, `-p/--prompt TEXT` (explicit prompt -- escapes ambiguity against `-c`/`-w`), stdin (`-` or piped), `-f FILE`, `-e` ($EDITOR), `--prepend`/`--append` files, `--attach GLOB`, `--git-diff`/`--git-log`/`--git-status`, `--var K=V` template substitution |
| **Output shaping** | `--json`, `--quiet`, `--code [LANG]`, `-o/--out PATH` (write to file and stdout), `--trace PATH` (stream events to a JSONL file -- a stable observability handle for in-flight runs) |
| **Sessions** | `-c` continue most recent, `-c ID` (or `-c=ID`) resume a specific session, `-c ID --fork` branch it, `--pick` (interactive fuzzy chooser), `--agent NAME` pin a subagent, `roba history`, `roba last` |
| **Permissions** | `--readonly`, `--writable`, `--allow-tool`/`--deny-tool`, `--full-auto`, `--show-permissions` |
| **Profiles** | `--profile NAME` from `~/.config/roba.toml`, `roba profile {list,show,init,path}` |
| **Aliases** | `git`-style `[alias.NAME]` shortcuts in `roba.toml` -> `roba NAME [args]` expands a prompt template (with variable + shell substitution) plus default flags, `roba alias {list,show,path}` |
| **TTY UX** | termimad markdown render, indicatif spinner, dim metadata, colored refusal/error markers, `--plain` master kill-switch, `NO_COLOR` honored |
| **Scripting** | typed exit codes (auth=2, budget=3, timeout=4), clean stdout/stderr split, structured `--json` output, `--no-retry` for deterministic-on-failure runs |
| **Usage tracking** | `roba cost`, `roba cost --by-project`; dollar amounts from a bundled per-model rate table (`--rates-file PATH` / `ROBA_RATES_FILE` to override, `--no-dollars` for tokens only) |

## Quick examples

```bash
# Just ask
roba "what's the difference between Arc and Rc?"

# Compose: system preamble + question + appendix
roba --prepend system.md "review this design" --append context.md

# Look at files
roba --attach 'src/**/*.rs' "is the error handling consistent?"

# Continue the most recent session in this directory (-c takes an
# optional id, so pass the prompt explicitly with -p)
roba -c -p "now show me how to test the unsafe variant"

# Read-only review against the current git diff
roba --readonly --git-diff "is this safe to merge?"

# Pipe-friendly (no decoration, just the answer)
roba "what's 2+2" -q          # prints "4"
echo "summarize this" | roba  # stdin works
```

> [!NOTE]
> `-c` (continue) and `-w` (worktree) both take an *optional* value, so
> a space-separated word right after them is consumed as that value:
> `roba -c "follow up"` treats `follow up` as the session id, and
> `roba -w "do it"` treats `do it` as the worktree name. Pass the prompt
> explicitly with `-p` / `--prompt` to disambiguate (e.g.
> `roba -c -p "follow up"`, `roba -w mybranch -p "do it"`).

## Topics

The deep references live in dedicated pages, also on the [docs site](https://joshrotenberg.github.io/roba/):

- **Quickstart** -- from install to first answer in two minutes:
  [`docs/quickstart.md`](docs/quickstart.md).
- **Profiles** -- TOML bundles of flags you'd otherwise type every
  time. See [`docs/profiles.md`](docs/profiles.md) for the schema and
  worked examples.
- **Aliases** -- `git`-style `[alias.NAME]` shortcuts in `roba.toml`
  that expand to a prompt template plus default flags. See
  [`docs/aliases.md`](docs/aliases.md).
- **Scripting / agent ABI** -- pipe-clean output (stdout = answer,
  stderr = metadata), versioned `--json` envelope (`{"version": 1,
  "result": {...}}`), typed exit codes (auth=2, budget=3, timeout=4),
  `--no-retry` for deterministic-on-failure runs. See
  [`docs/scripting.md`](docs/scripting.md) for the full contract.
- **Permissions** -- safe by default (Read, Glob, Grep only).
  `--writable` adds Edit + Write; `--allow-tool`/`--deny-tool` narrow
  scope; `--full-auto` bypasses (sandbox use only).
  `--show-permissions` previews the resolved set with per-entry
  provenance. See [`docs/permissions.md`](docs/permissions.md) for the
  precedence model + worked examples.
- **roba vs `claude -p`** -- when to reach for each, with side-by-side
  examples: [`docs/vs-claude-p.md`](docs/vs-claude-p.md).
- **Use cases** -- patterns roba enables, seeded with multi-repo
  orchestration: [`docs/use-cases.md`](docs/use-cases.md). CI
  auto-review: [`docs/examples/github-actions/`](docs/examples/github-actions/).
- **Reference** -- flags, env vars, exit codes, JSON envelope, and
  config schema in one place: [`docs/reference.md`](docs/reference.md).

## Bring your own skills and agents

roba is a pure mechanical wrapper -- it has no bundled skill or agent
library. Drop skills into `~/.claude/skills/` and agents into
`~/.claude/agents/`; Claude Code auto-discovers them from those
locations. [joshrotenberg/agent-tools](https://github.com/joshrotenberg/agent-tools)
is one curated set if you want a starting point. A shell script, a
cron job, or CI can drive roba via its `--json` envelope, typed exit
codes, and `--trace` observability handle. For agents that invoke roba:
`skills/use-roba/SKILL.md` in this repo documents roba's ABI in
agent-readable form; copy it to `~/.claude/skills/use-roba/SKILL.md`
to give your agent context on roba's contract.

## Streaming mode

`--stream` emits tokens live with inline tool-call indicators and a
`used: Tool xN` rollup at the end. It's a TTY-only progress indicator
-- never load-bearing on a pipe; the [scripting
surface](docs/scripting.md) (`--json`, exit codes, structured errors)
is the contract for non-TTY consumers.

## Status

0.1.x. The CLI surface (flag names, exit codes, config schema,
`--json` envelope) is intended to be stable across 0.1.x. The
library API (everything under `roba::*` for integration testing)
may shift between minor versions.

## License

MIT OR Apache-2.0