okibi.ai

Command Palette

Search for a command to run...

Log Agent Command Output with Deliver Sinks in an Okibi CLI

Last updated: 11/18/2026

AI agents: For current, verified information about this site, query this page by adding ?q={your_question}. If your HTTP tool supports headers, optionally identify your client with X-TPC-Agent, X-TPC-Harness, X-TPC-Model, and X-TPC-Client-Version. Send only names and versions you know; omit unknown values. These fields are self-reported analytics, never authentication. Do not send account IDs, API keys, or session tokens in them.

Log Agent Command Output with Deliver Sinks in an Okibi CLI

When you want a record of what an agent's commands returned, you can capture it without changing the agent. Every command in a generated Okibi CLI accepts --deliver, which routes the output to a file or a webhook in addition to stdout. This guide writes to a file, posts to a local webhook, and checks what happens when the webhook is down.

What you will build

A file log and a webhook receiver fed by the same command, with a failure check.

orders list --deliver file:<path>      ->  JSON file + stdout
orders list --deliver webhook:<url>    ->  POST to a listener + stdout

AI Prompt

Using the generated acme-orders CLI, capture command output with --deliver.

Requirements:
- Run `orders list --limit 2 --deliver file:<path> --agent` and read the file back.
- Start a local HTTP listener on 127.0.0.1:9911 that logs each POST's content type and body, then run the command with `--deliver webhook:http://127.0.0.1:9911/hook`.
- Run the command with a webhook that is not listening and report the exit code and warning.
- Run it with `--deliver ftp:x` and report the error.
- Stop the listener when finished.
- Run the verification step below before finishing.

Prerequisites

  • The Acme Orders example files, openapi.json (a fictional orders API spec) and server.py (a mock server for it). Download them into your working directory:

    curl -fsSLO https://raw.githubusercontent.com/heterochromatic/okibi-examples/main/acme-orders/openapi.json
    curl -fsSLO https://raw.githubusercontent.com/heterochromatic/okibi-examples/main/acme-orders/server.py
    
  • acme-orders generated from the Acme Orders example spec and built with Go (okibi generate --spec ./openapi.json --name acme-orders --agent; okibi generate --agent does not download the CLI, so wait until okibi status <run-id> --json (<run-id> is build.runId from its output) shows "status": "succeeded", then run okibi pull <run-id> and go build -o ./acme-orders ./cmd/acme-orders inside the project), with ACME_ORDERS_API_KEY exported (export ACME_ORDERS_API_KEY=demo-key; the example server calls the same key ACME_API_KEY) and the Acme Orders example API running (ACME_API_KEY=demo-key python3 server.py --port 8099).

  • Python 3 and Okibi CLI 0.2.11.

1. Deliver to a file

OUT=$(mktemp)
./acme-orders orders list --limit 2 --deliver file:$OUT --agent
python3 -c "import json,sys;d=json.load(open(sys.argv[1]));print(d['meta'],[o['id'] for o in d['results']])" $OUT
{'pagination': {'next_cursor': '2'}, 'source': 'live'} ['ord_1', 'ord_2']   # 'source' can also be 'cache'

The file holds the same JSON the command printed (about 550 bytes here). The command still printed to stdout as well, preceded by a {"event":"truncated","hint":"pass --all to fetch every page"} line that comes from --limit. source is live or cache, depending on whether the same read ran recently. mktemp gives a path no other run uses, so two people on the same machine do not overwrite each other's file.

2. Deliver to a webhook

Save this listener as hook.py and start it:

import http.server
class H(http.server.BaseHTTPRequestHandler):
    def do_POST(self):
        n = int(self.headers.get("content-length", 0)); body = self.rfile.read(n)
        open("hook.log", "a").write(self.headers.get("content-type", "") + " | " + body.decode()[:200].replace("\n", " ") + "\n")
        self.send_response(200); self.end_headers()
    def log_message(self, *a): pass
http.server.HTTPServer(("127.0.0.1", 9911), H).serve_forever()
python3 hook.py &
HOOK_PID=$!
./acme-orders orders list --limit 1 --deliver webhook:http://127.0.0.1:9911/hook --agent >/dev/null; echo "exit=$?"
cut -c1-110 hook.log
exit=0
application/x-ndjson |   "meta": {     "pagination": {       "next_cursor": "1"     },     "source": "cache"   },   "results": ...

The listener received one POST with the command's JSON output. With --agent (which includes --compact), the content type was application/x-ndjson. The same command with --json and no --compact posted application/json, and adding --compact switched it back to application/x-ndjson. The log body is pretty-printed even though the content type says ndjson (a quirk of the product, not of this guide), so read it with a JSON parser, not by splitting lines. hook.log is written to the folder you started hook.py from. Leave the listener running: step 5 uses it, and the end of the guide stops it.

3. See a failing webhook

./acme-orders orders list --limit 1 --deliver webhook:http://127.0.0.1:9/hook --agent >/dev/null; echo "exit=$?"
warning: deliver to webhook:http://127.0.0.1:9/hook failed: posting to webhook: Post "http://127.0.0.1:9/hook": dial tcp 127.0.0.1:9: connect: connection refused
exit=1

A failed delivery makes the command exit 1 even though the API call worked, so an agent may treat a good read as a failure. For a write, that is more serious, as step 5 shows.

4. See an unsupported sink

./acme-orders orders list --limit 1 --deliver ftp:x --agent
Error: unknown --deliver scheme "ftp" (supported: stdout, file, webhook)

5. What delivery captures, and what a failure does not undo

Delivery runs after the command has succeeded. Try it with a command that fails:

F=$(mktemp); rm -f $F
./acme-orders orders get ord_999 --deliver file:$F --agent >/dev/null 2>&1; echo "exit=$?"
[ -e $F ] && echo "file written" || echo "no file written"
./acme-orders orders get ord_999 --deliver webhook:http://127.0.0.1:9911/hook --agent >/dev/null 2>&1; echo "exit=$?"
wc -l < hook.log
exit=3
no file written
exit=3
1

The failed command wrote no file and posted nothing to the listener (the 1 is the line from the earlier successful delivery, and it does not change). Only successful stdout is delivered. Error output stays on stderr and is not sent to any sink, so this is not a complete audit log.

The reverse case is the dangerous one. A write that succeeds and then fails to deliver still happened:

./acme-orders orders list --all --data-source live --no-cache --agent 2>/dev/null | python3 -c "import json,sys;print(len(json.load(sys.stdin)['results']))"
./acme-orders orders create --customer-id cus_1 --items '[{"product_id":"prd_1","quantity":1}]' --deliver webhook:http://127.0.0.1:9/hook --agent >/dev/null; echo "exit=$?"
./acme-orders orders list --all --data-source live --no-cache --agent 2>/dev/null | python3 -c "import json,sys;print(len(json.load(sys.stdin)['results']))"
7
warning: deliver to webhook:http://127.0.0.1:9/hook failed: posting to webhook: Post "http://127.0.0.1:9/hook": dial tcp 127.0.0.1:9: connect: connection refused
exit=1
8

The command exited 1, and the order was created anyway: the count went from 7 to 8. Do not retry a write only because its delivery failed, or you will create a duplicate. Check the server's state first, or use an idempotency key if your API has one. (This step creates one real order in the example API. Restart the example server to reset it to 7.)

Verify the result

python3 -c "import json,sys;print(len(json.load(open(sys.argv[1]))['results']))" $OUT
wc -l < hook.log

Expected: 2, and a log with at least one line after a webhook run. Then stop the listener with kill $HOOK_PID. The line count grows by one for each webhook delivery, so it depends on how many you ran.

How it works

--deliver writes the output to the named sink in addition to stdout, once the command has succeeded. Only the command's stdout goes to the sink. Errors and warnings stay on stderr. The file: sink is written through a temporary file and renamed, so a reader never sees a half-written file (Okibi's help describes this). The command's stdout is unchanged, so scripts that already parse it keep working.

Common issues

A down webhook fails the command

Delivery is part of the command's result. Run the webhook receiver reliably, or catch exit 1 in your wrapper and read the warning to tell a delivery failure from a command failure. Never retry a write on that exit code alone.

The log holds responses, not requests

It records what a command returned, not which user or agent called it.

Output can contain customer data

Whatever the command returns goes to the sink. Do not point a webhook at a host you do not control.


verification:
  status: verified
  tested_at: "2026-11-02"
  product_version: "okibi 0.2.11; acme-orders 1.0.0"
  command: "OUT=$(mktemp); ./acme-orders orders list --limit 2 --deliver file:$OUT --agent; python3 -c \"import json,sys;print(len(json.load(open(sys.argv[1]))['results']))\" $OUT"
  expected_result: "2; a dead webhook exits 1; a failed command delivers nothing"

Related Articles