clnkrd(1)

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
clnkrd runs clnkr behind a newline-delimited JSON protocol on standard input and standard output. A frontend writes one JSON command per line to stdin. clnkrd writes one JSON event per line to stdout.

Normal diagnostics, flag errors, configuration errors, JSONL decode errors, and run errors are written to stderr. In JSONL mode, stdout is reserved for protocol events.

clnkrd is a stdio adapter. It does not open sockets, authenticate clients, serve HTTP, host plugins, or manage a background service lifecycle.

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.

JSONL COMMANDS
Every stdin line is one JSON object with a type field.

prompt
    Start a run. Requires text and mode. mode is approval or full_send. Only one prompt can run at a time.

        {"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 is sent back to the model as guidance.

        {"type":"reply","text":"y"}

compact
    Compact older transcript history. Optional instructions are passed to the compaction summarizer.

        {"type":"compact","instructions":"keep test failures and decisions"}

shutdown
    Cancel an active run, drain pending events, and exit successfully.

        {"type":"shutdown"}

JSONL EVENTS
Every stdout event is a JSON object with type and payload fields.

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.

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.

--event-log writes the same JSONL event stream to a file while also writing events to stdout.

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"

EXIT STATUS

0   Clean EOF on stdin, shutdown, --help, --version, or --dump-system-prompt.

1   Invalid flags, missing provider configuration, bad JSONL input, invalid command sequencing, session load failure, provider error, command/run error, or event write failure.

130 Interrupted by SIGINT.

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)