Aaron Norling

The Twelve-Factor Utility

The Twelve-Factor App methodology has aged well. Its staying power comes from a simple idea: treat each operational concern as a first-class design constraint, and scalability and portability become properties of the application rather than problems to solve later.

The same spirit applies to a humbler artifact: the command-line utility. If you’re impatient, jump to the twelve factors.

Discovery

I wrote ContextQ as a standalone CLI — a small queue tool for managing context items at the terminal. I kept the design tight: all state under a single root directory, clean JSON output with --json, structured errors, atomic writes. Good CLI hygiene, not a grand plan.

When I later built contextq-server, something became clear in retrospect. The server wasn’t a new implementation of queue logic. It was a thin wrapper — an argv adapter that handled authentication, namespacing, and HTTP, then called the CLI as a subprocess. The CLI already owned every hard part: domain semantics, concurrency correctness, storage integrity.

The server was cheap to write because the CLI was already strong.

The Pattern

Build the CLI as though its stdout, stderr, argv, exit status, and storage root are a public protocol. A generic shell can then turn that protocol into authenticated remote access without learning the application’s domain.

The twelve properties below define what “owns its domain” means in practice. Each one is a design constraint that costs a little at authoring time and pays back at every integration that follows.

The Twelve Factors

1. Complete Rootability

All durable state lives beneath --root <path>. Application state does not leak through $HOME, the current directory, global configuration, or implicit caches.

You get: namespace isolation, backup boundaries, and safe multi-tenant operation through path substitution alone.

2. Machine Protocol Mode

Every exposed command supports --json. Success writes one valid JSON document to stdout and exits zero. Diagnostic output never contaminates the JSON stream. Output schemas remain compatible within a declared protocol version.

You get: transparent RPC responses — the wrapper forwards stdout directly without parsing or reformatting.

3. Stable Machine-Readable Errors

Failures carry a stable code independent of their prose:

{
  "code": "duplicate_key",
  "error": "key already exists"
}

The code is part of the contract. The human-readable message is not.

You get: HTTP status mapping and client branching without text parsing. A manifest can map duplicate_key to 409 declaratively.

4. Stable Command Grammar

Subcommand paths, flags, and positionals don’t shift between versions without a protocol version bump. The command surface is stable and enumerable.

You get: declarative command allowlisting — a manifest can enumerate permitted commands and the shell can enforce that list without knowing what those commands do.

5. Process-Safe State

Concurrent invocations remain correct without external coordination. Mutations use file locks, database transactions, or atomic replacement. The wrapper may cap concurrency to protect the host, but it is never the authority for domain locking.

You get: safe concurrent requests — the shell doesn’t need to serialize calls to preserve correctness.

6. Short, One-Shot Execution

Commands complete quickly and do not daemonize. The CLI is invoked, does its work, and exits. It does not detach child processes, hold open file handles, or assume a long-lived session.

You get: one subprocess per HTTP request — a simple, predictable execution model with no session management overhead.

7. No Terminal Dependency

The CLI does not require an interactive terminal. No prompts, no TTY assumptions, no readline. Every path can be driven non-interactively.

You get: unattended remote execution — the shell can invoke the CLI as a subprocess in any environment without simulating a terminal.

8. Deterministic Environment

The CLI does not rely on ambient environment state. No inherited PATH, HOME, plugins, or user configuration. The runtime dependency set is closed and explicit.

You get: reproducible server behavior — the shell controls the environment and the CLI behaves identically regardless of who or what invokes it.

9. Bounded Output

Large collections support limits, cursors, or pagination. Commands do not emit unbounded streams. Output is sized for buffering.

You get: safe response buffering — the shell can collect, validate, and forward output without streaming infrastructure.

10. Cancellation-Safe Mutations

Termination cannot leave partially written state. A command either commits a valid mutation or leaves the previous state intact. Interrupted operations are recoverable without manual cleanup.

You get: request timeouts — the shell can cancel a slow subprocess without corrupting application state.

11. Version and Capability Introspection

A probe command reports application version, command protocol version, and storage format version:

contextq version --json

You get: startup compatibility checks — the shell can verify it is speaking the right protocol before accepting live requests, catching mismatches at deploy time rather than at runtime.

12. Explicit Retry Semantics

Mutations accept an idempotency key, or natural idempotency is part of the command contract. The wrapper should not silently retry non-idempotent commands.

You get: safe client retries — network failures don’t require manual state inspection to recover.

The Leverage

These twelve constraints might look like a checklist. I’d suggest thinking of them as a design posture.

None of them are expensive to apply when writing a new CLI from scratch. Taken together, they produce a utility that is:

  • Trivially testable — deterministic input, structured output, no environmental leakage
  • Easily composed — rootable, one-shot, no hidden state
  • Safely wrappable — strong enough to become a network boundary without modification

The last point is the one that surprised me. When I extracted the server from ContextQ’s repository, the application-specific code was almost nothing. Authentication, namespacing, request routing, audit logging — all of it was generic. The only thing the server needed to know about ContextQ was which commands to allow, which errors to map to which HTTP statuses, and where to find the binary.

That’s the return on investment. Design the utility this way once. Every integration — a server wrapper, a CI step, a scheduled job, a test harness — is cheaper as a result.

The Twelve-Factor App taught us to treat operational concerns as first-class constraints during development, not as problems to solve at deploy time. The same principle scales down. A CLI utility that owns its domain, respects its process boundary, and speaks a machine-readable protocol earns something valuable: the right to be served, scripted, and integrated — without asking the next author to rewrite what already works.

Build the utility. The server comes almost for free.