Open questions

Back to the spec index

The spec files hold only settled rules. Everything open or merely suggested is here. When a question is decided, write the rule into the spec file it belongs to and delete it from this list.

Last checked: 2026-11-02.

Naming and grammar

1. Vocabulary. Read/write, or query/mutation, as the values of a command’s class in describe? The spec currently uses “query” and “mutation” as working terms.
   • For query/mutation: matches GraphQL and CQRS, which agents and developers already know. “Mutation” covers delete, replace, and lock-taking, which “write” blurs.
   • Against: read/write is already common in tool names, for example acme-read / acme-write. “Query” can sound like “search” only. Two word pairs in one spec confuse people.
   • Leaning: use query/mutation as the term for a command’s class, and keep binary names (if an adopter splits a tool) their own choice.
   • Affects: section 2 and section 8.
2. Describe command name. describe or schema? Section 8 currently says describe.
3. Version number scheme. Which scheme does <cli> version use, for example MAJOR.MINOR.PATCH? Section 3.

Output and errors

4. Styling off, text format. When styling is off (NO_COLOR, -no-color, TERM=dumb, or not a TTY) and the format is text, are the markdown marks written? Proposal: yes, since styling was the only signal. Marks then appear only when styling is off, and styling appears only when marks are dropped. The result is never plain text with no emphasis. This would also make text with styling off identical to md. Sections 4 and 5.
5. NO_COLOR and bold. NO_COLOR strictly covers colour, not bold. The spec turns off all ANSI styling, bold included, when NO_COLOR is set, so one switch controls everything. Alternative: keep bold on under NO_COLOR and write marks only for the coloured spans. Section 4.
6. Resource shape. What shape do CLIs use for resources inside result? Proposal: K8s-style apiVersion / kind / metadata / spec / status, with items for lists, and the same shape for output of get and input of upsert, so one can be piped to the other. The spec currently says only that the payload shape is the CLI’s choice. Section 4.
7. Suggested mutations. Proposal: a suggested command for a mutation (in an error’s remediation or next) never includes -confirm. Section 8.

Testing

8. Conformance suite. Whether to write a conformance suite as part of this repo, and in what form (for example a list of cases in data files, so no language is favoured). Section 10.

Rules never explicitly reviewed

9. Unmarked rules. These sections hold rules that were written but never reviewed one by one. They are treated as accepted for now. Confirm or change them:
   • Locking basics: lock before writing, release after a crash, and atomic rename for crash-safe writes (section 7).
   • The -help layout, the doc command, and shell completions (section 8).
   • The conformance checks and golden tests listed in section 10.