12-Factor AI-enabled CLI (12fc)
claimed by its maintainerTwelve testable factors for a command-line tool whose operator may be a human or an AI agent, from machine-readable capabilities to meaningful exit codes, with a conformance gate.
Canonical text: https://github.com/hop-top/spec-12fc/blob/main/specs/v0.1/spec.md, read against version 0.1.
The twelve factors
- Capability introspection. The CLI exposes its capabilities in a machine-readable format.
- Intent clarity. Commands express intent, not syntax.
- Structured I/O. Machine-readable output with a stable schema, strict channel discipline.
- Corrective error model. Errors carry a stable code, the failing input, a transience class and a suggested fix.
- Explicit contracts. Idempotency, side effects, retry semantics, schema versioning and partial failure are declared.
- Previewability. Every mutating operation can be previewed; nothing blocks on a prompt without a TTY.
- Idempotency by default, or declared otherwise with a safe retry strategy.
- State transparency. All implicit state is inspectable.
- Contextual guidance. Help that answers the situation, not the flag list.
- Delegation safety. Scoped permissions, confirmation policies, sandboxing, rate limits, policy enforcement.
- Exit code semantics. Zero means success, never a swallowed error; failure classes are distinguishable.
- Evolution guarantees. Changes announce themselves; renaming an error code is a breaking change.
Facts
- Maintainer
- hop.top, published by Idea Crafters
- Repository
- https://github.com/hop-top/spec-12fc
- First published
- 2026-04
- Status of the text
- draft
- Listing
- claimed by the maintainer, 2026-10-25
Read with
- claimed
Agent Operation Protocol
Six laws a system must enforce at its API boundary so that any actor, human or agent, can act on a shared operational graph without breaking it.
- claimed
Purpose-bound Access Control and Trust
How an AI agent proves who it acts for, with what declared purpose and evidence, to a gateway that already authenticates and authorizes; a PACT pass never grants access and a native denial always wins.
v1.0.0-alpha.0 Agentic Stack -
The Twelve-Factor App
Twelve factors for building software-as-a-service applications that are portable, declarative and ready to scale, written at Heroku from experience operating hundreds of thousands of apps.
-
12-Factor Agents
Principles for building LLM-powered software reliable enough to put in front of production customers, modelled on the Twelve-Factor App and maintained in the open.
Badge
[](https://manifesto.md/12fc/)