Streams & Exit Codes

# Data to a file, messages still visible on the terminal
docsctl search kalman --json > results.json

# Data to a file, messages to a log: both are clean
docsctl search kalman --json > results.json 2> docsctl.log

# Silence the noise entirely; the exit code still reports failure
docsctl validate . --quiet > /dev/null 2>&1

# Merge the streams only when a person wants a transcript (never when parsing)
docsctl validate . > transcript.txt 2>&1

import json
import sys


def emit_result(result: dict) -> None:
    """The answer: stdout only, one JSON document, keys sorted for stable diffs."""
    json.dump(result, sys.stdout, sort_keys=True)
    sys.stdout.write("\n")


def note(message: str) -> None:
    """Commentary: stderr only."""
    print(f"docsctl: {message}", file=sys.stderr)

# Titles of the top five hits, one per line
docsctl search kalman --json --limit 5 | jq -r '.results[].title'

# The components that have more than one published version
docsctl list-components --include-versions --json \
  | jq -r '.components[] | select(.versions | length > 1) | .name'

# Feed page ids to another docsctl call; one id per line, so xargs splits them safely
docsctl search kalman --json --limit 3 | jq -r '.results[].id' \
  | xargs -n 1 docsctl show --max-chars 500 --

import os
import sys


def main() -> int:
    for line in produce_lines():
        print(line)
    return 0


if __name__ == "__main__":
    try:
        code = main()
        sys.stdout.flush()
    except BrokenPipeError:
        # Python flushes stdout again at exit; point it at /dev/null to avoid a second error
        devnull = os.open(os.devnull, os.O_WRONLY)
        os.dup2(devnull, sys.stdout.fileno())
        code = 1
    sys.exit(code)

{"schemaVersion":1,"error":{"code":"AUTH_REQUIRED","exitCode":7,"message":"No credentials found.","hint":"Run `docsctl login` or set DOCSCTL_TOKEN.","retryable":false,"details":{}}}

#!/usr/bin/env bash
set -uo pipefail

docsctl search kalman --json --limit 5 > results.json 2> error.json
status=$?   # capture it immediately: the next command overwrites $?

case "$status" in
  0) jq -r '.results[].id' results.json ;;
  2) echo "bad command line: $(jq -r '.error.message' error.json)" >&2; exit 2 ;;
  6) echo "transient failure, retrying later" >&2; exit 6 ;;   # pass the retryable status on to the scheduler
  7) echo "not logged in: $(jq -r '.error.hint' error.json)" >&2; exit 7 ;;
  127) echo "docsctl is not installed" >&2; exit 127 ;;
  *) echo "docsctl failed with status $status" >&2; cat error.json >&2; exit "$status" ;;
esac

import json
import sys

EXIT_OK, EXIT_INTERNAL, EXIT_USAGE, EXIT_VALIDATION = 0, 1, 2, 3
EXIT_NOT_FOUND, EXIT_CONFIRM, EXIT_RETRYABLE, EXIT_AUTH = 4, 5, 6, 7


class CliError(Exception):
    def __init__(self, code: str, exit_code: int, message: str, hint: str = "", retryable: bool = False):
        super().__init__(message)
        self.code, self.exit_code, self.hint, self.retryable = code, exit_code, hint, retryable


def report(err: CliError, json_mode: bool) -> int:
    if json_mode:
        envelope = {
            "schemaVersion": 1,
            "error": {
                "code": err.code,
                "exitCode": err.exit_code,
                "message": str(err),
                "hint": err.hint,
                "retryable": err.retryable,
                "details": {},
            },
        }
        print(json.dumps(envelope, sort_keys=True), file=sys.stderr)
    else:
        print(f"docsctl: {err}", file=sys.stderr)
        if err.hint:
            print(f"hint: {err.hint}", file=sys.stderr)
    return err.exit_code


def main(argv: list[str]) -> int:
    json_mode = "--json" in argv
    try:
        run(argv)  # writes the result to stdout
        return EXIT_OK
    except CliError as err:
        return report(err, json_mode)
    except Exception as exc:  # a bug: say so, keep the traceback on stderr, use the generic code
        print(f"docsctl: internal error: {exc}", file=sys.stderr)
        return EXIT_INTERNAL


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))

import subprocess

proc = subprocess.run(
    ["docsctl", "search", "--json", "--limit", "5", "--", "kalman"],  # argv list, never a shell string
    capture_output=True,
    text=True,
    timeout=30,
    check=False,
)

code = proc.returncode
if code < 0:
    # Python reports "killed by signal N" as -N; a shell would show 128 + N
    code = 128 + (-code)

if code == 0:
    ...  # parse proc.stdout
elif code == 6:
    ...  # retryable: wait and try again
elif code == 7:
    ...  # not logged in: proc.stderr holds the JSON error envelope with the hint

import signal
import sys
import tempfile
from pathlib import Path


def install_signal_handlers() -> None:
    def stop(signum, _frame):
        # Raising SystemExit runs the finally blocks below, then exits with the conventional code
        raise SystemExit(128 + signum)

    signal.signal(signal.SIGINT, stop)   # Ctrl-C  -> 130
    signal.signal(signal.SIGTERM, stop)  # kill    -> 143


def main() -> int:
    install_signal_handlers()
    workdir = Path(tempfile.mkdtemp(prefix="docsctl-"))
    try:
        ...  # long-running work that writes to workdir
        return 0
    finally:
        for child in workdir.iterdir():
            child.unlink()
        workdir.rmdir()  # one quiet cleanup, then exit


if __name__ == "__main__":
    sys.exit(main())