clnkrd(1)

📦 version 0.3.11, in ubuntu stonking

✨ clnkrd — your stdio JSONL bestie for clnkr ✨

no cap, this is clnkrd(1) from the General Commands Manual section, and we are going all the way through it, every last flag, periodt 💅

🎀 NAME 🎀

clnkrd — stdio JSONL adapter for clnkr

🌸 SYNOPSIS 🌸

clnkrd [--model name] [--base-url url] [--provider mode] [--provider-api surface] [--act-protocol protocol] [--effort level] [--thinking-budget-tokens n] [--max-output-tokens n] [--max-steps n] [--continue] [--load-messages file] [--event-log file] [--no-system-prompt] [--system-prompt-append text] [--dump-system-prompt] [--version]

💖 DESCRIPTION 💖

okay so picture this: clnkrd runs clnkr behind a newline-delimited JSON protocol on standard input and standard output. Your frontend writes one JSON command per line to stdin, and clnkrd writes one JSON event per line to stdout. that's the whole vibe. 🦋

Normal diagnostics, flag errors, configuration errors, JSONL decode errors, and run errors all go to stderr. in JSONL mode, stdout is reserved for protocol events — do not touch it, it's booked 💀

clnkrd is a stdio adapter. it does not open sockets, authenticate clients, serve HTTP, host plugins, or manage a background service lifecycle. it's giving minimal. it's giving boundaries. we love that for it ✨

fun fact: clnkr can launch clnkrd through bash for bounded child work. in that use, clnkrd is still just a stdio JSONL process; stdout, stderr, and --event-log are the child artifact surfaces. iykyk 🧚

🌈 JSONL COMMANDS 🌈

Every stdin line is one JSON object with a type field. one line, one object, no cap.

  • prompt — start a run. it needs text and mode. mode is approval or full_send. only one prompt can run at a time, so no multitasking bestie 😭
{"type":"prompt","text":"inspect this repo","mode":"approval"}
  • reply — answer a pending approval_request or clarify event. for approval, text equal to y approves the command batch. any other non-empty text rejects the batch and gets sent back to the model as guidance. so y is the yes, and literally anything else is a whole conversation.
{"type":"reply","text":"y"}
  • compact — compact older transcript history. optional instructions get passed to the compaction summarizer, so say what you want kept.
{"type":"compact","instructions":"keep test failures and decisions"}
  • shutdown — cancel an active run, drain pending events, and exit successfully. the graceful goodbye 🫶
{"type":"shutdown"}

👑 JSONL EVENTS 👑

Every stdout event is a JSON object with type and payload fields. here's the whole roster:

  • debug — diagnostic metadata and internal progress. Payload: message.
  • response — accepted model turn. Payload: turn, usage, and optional raw. usage contains input_tokens and output_tokens.
  • protocol_failure — rejected model response. Payload: reason and raw. not every message makes the cut 💀
  • approval_request — command batch waiting for a reply. Payload: prompt and commands. Each command has command and optional workdir.
  • clarify — user question waiting for a reply. Payload: question.
  • command_start — command execution started. Payload: command and dir.
  • command_done — command execution finished. Payload: command, stdout, stderr, exit_code, feedback, and optional err.
  • compacted — transcript compaction completed. Payload: compacted_messages and kept_messages.
  • done — prompt run completed. Payload: summary.
  • error — driver-visible run error. Payload: message.

💅 OPTIONS 💅

clnkrd accepts the same provider, prompt, session, and run-control options as the clnkr CLI where they apply to non-interactive operation: --model, --base-url, --provider, --provider-api, --act-protocol, --effort, --thinking-budget-tokens, --max-output-tokens, --max-steps, --continue, --load-messages, --event-log, --no-system-prompt, --system-prompt-append, --dump-system-prompt, and --version.

and listen: --event-log writes the same JSONL event stream to a file while also writing events to stdout. two places at once. she's versatile 💖

🦋 CHILD ORCHESTRATION EXAMPLE 🦋

Run one bounded child and inspect its JSONL events:

children=$(mktemp -d /tmp/clnkr-children.$$.XXXXXX)
mkdir -p "$children/readme"
printf '%s\n' '{"type":"prompt","text":"Inspect README.md. Do not edit files. Return evidence and uncertainty.","mode":"full_send"}' |
  clnkrd --event-log "$children/readme/events.jsonl" \
    > "$children/readme/out.jsonl" \
    2> "$children/readme/err"
sed -n '1,200p' "$children/readme/out.jsonl"

Run two independent children in parallel, then synthesize their output:

children=$(mktemp -d /tmp/clnkr-children.$$.XXXXXX)
mkdir -p "$children/code" "$children/docs"
printf '%s\n' '{"type":"prompt","text":"Review prompt.go for clnkrd child orchestration risks. Do not edit.","mode":"full_send"}' |
  clnkrd --event-log "$children/code/events.jsonl" \
    > "$children/code/out.jsonl" 2> "$children/code/err" & pid1=$!
printf '%s\n' '{"type":"prompt","text":"Review doc/*.1.md for child orchestration docs. Do not edit.","mode":"full_send"}' |
  clnkrd --event-log "$children/docs/events.jsonl" \
    > "$children/docs/out.jsonl" 2> "$children/docs/err" & pid2=$!
wait "$pid1" "$pid2"
sed -n '1,200p' "$children/code/out.jsonl"
sed -n '1,200p' "$children/docs/out.jsonl"

two children, running in parallel, minding their own business. main character energy fr fr 👑

⭐ EXIT STATUS ⭐

  • 0 — clean EOF on stdin, shutdown, --help, --version, or --dump-system-prompt. the happy endings 🎀
  • 1 — invalid flags, missing provider configuration, bad JSONL input, invalid command sequencing, session load failure, provider error, command/run error, or event write failure. a lot of ways to trip, bestie, watch your step 😭
  • 130 — interrupted by SIGINT. Ctrl+C said "enough" 💀

🍓 ENVIRONMENT 🍓

  • CLNKR_API_KEY — API key for the LLM provider.
  • CLNKR_PROVIDER — provider adapter semantics.
  • CLNKR_PROVIDER_API — OpenAI-only API surface override.
  • CLNKR_MODEL — default model identifier when --model is not provided.
  • CLNKR_BASE_URL — default LLM endpoint when --base-url is not provided.

🧚 SEE ALSO 🧚

clnkr(1), clnkr(3), clnkr(7)

and that's the whole page, bestie 💜 this one lives in the User Commands section of the manual, filed under clnkrd(1) — go read it, go run it, go slay ✨🌸
📦 where this page comes from