CML — the CLI we're building
cml status
cml is a small command-line tool we're designing — to read systems top-down, sign every deploy, and replay rollbacks in under a second. Nothing here is installable yet. We're publishing the design in the open so it can be argued with before it's built.
Built in three tiers.
- Tier 01 · read-only
read · mist
Built first. Read-only by design — never modifies a repo or a deploy. Safe to put in front of clients early.
- Tier 02 · additive
sign · field
Built next. Adds signing and the field-notes publisher. Writes new artefacts; doesn't change existing ones.
- Tier 03 · destructive
deploy · rollback
Built last, and slowly. These touch production. We don't ship them until tier 01 and tier 02 have survived a full engagement.
No installer yet. No public repo yet. When tier 01 ships, this section becomes an install panel. Until then, talk to us via hello@cloudmistlabs.com.
$ cml status
· cml is in design — nothing implemented yet
· planned commands: read · mist · sign · field · deploy · rollback
· follow at /cml
$ cml read --strata ./src # preview
· (would walk src/, group files by stratum,
· write a map to .cml/map.md, exit)
$ cml deploy --strata edge,services # preview
· (would refuse without a signature)
· (would refuse without 99.95% shadow-read for 9 days)
$ Six verbs. That's it.
Most tools collapse under their own surface area. cml is six commands, on purpose. If a flag exists, it does one thing and refuses to do the other.
Below is the planned API. Status badges show what's implemented today.
- cml read planned01 — read-onlycml read [--strata] [--order top-down|bottom-up] <path>
Walk a repo top-down and produce a map of every stratum it contains. Reads commits backwards from HEAD. Outputs Markdown.
Flags- --strata
- Group the output by stratum (Edge / Services / Data).
- --order
- Reading direction. Defaults to top-down.
- --since <commit>
- Only read changes since the given commit.
- -o, --out <file>
- Write to a file instead of stdout.
$ cml read --strata --order top-down ./src*Planned API. Subject to change before any release.*
- cml sign planned02 — additivecml sign [--key <email>] [--checkpoint <n>]
Sign a deploy or a checkpoint. The signature is the proof. Uses your local key or one you specify.
Flags- --key <email>
- The signing identity. Defaults to git user.email.
- --checkpoint <n/N>
- Mark this as the Nth of N checkpoints in a migration.
- --witness <email>
- Add a witness signature. Can be repeated.
$ cml sign --key ghaith@cloudmistlabs.com --checkpoint 04/08*Planned API. Subject to change before any release.*
- cml deploy planned03 — destructivecml deploy --strata <list> [--signed] [--shadow <pct>]
Roll out one or more strata. Refuses to deploy unsigned by default. Refuses to flip a read path until shadow-read targets are met.
Flags- --strata <list>
- Comma-separated strata to deploy. Order matters.
- --signed
- Require a valid signature before deploying.
- --shadow <pct>
- Required shadow-read percentage. Defaults to 99.95.
- --days <n>
- Required shadow-read window in days. Defaults to 9.
$ cml deploy --strata edge,services --signed*Planned API. Subject to change before any release.*
- cml rollback planned03 — destructivecml rollback [--rehearse] [--to <checkpoint>]
Replay the rollback for the most recent deploy. Use --rehearse to do it on a staging environment without touching production.
Flags- --rehearse
- Rehearse only. Don't affect production.
- --to <checkpoint>
- Roll back to a specific checkpoint number.
- --explain
- Print what would happen, then exit.
$ cml rollback --rehearse --to 04/08*Planned API. Subject to change before any release.*
- cml field planned02 — additivecml field [new|sign|publish] <slug>
Field notes — short essays. Each field note is signed, dated, and goes through the same rollback rehearsal as code.
Flags- new <slug>
- Start a new note. Opens $EDITOR.
- sign <slug>
- Sign and freeze the note.
- publish <slug>
- Push to the public field-notes feed.
$ cml field new on-reading-systems*Planned API. Subject to change before any release.*
- cml mist planned01 — read-onlycml mist [--report] [--quiet]
Print a one-page report of the current state of all strata. The quiet command. Run it every morning.
Flags- --report
- Write a Markdown report to .cml/mist.md.
- --quiet
- Suppress everything except exit code.
$ cml mist --report*Planned API. Subject to change before any release.*
Three ideas the tool is built on.
- · 01 ·
Strata
Every codebase has three layers — Edge, Services, Data. cml will map them, refuse to deploy out of order, and sign each boundary.
- · 02 ·
Signatures
Every deploy carries a signature. Every checkpoint carries witness signatures. Replay is verification, not theatre.
- · 03 ·
Quiet by default
No telemetry, no spinner animations, no "✨ awesome!". cml prints what changed and exits. The quiet command is the correct one.
Where this goes next.
- Tier 01 release when read-only commands are stable and have been used internally read + mist. Installable but pre-1.0. Reads only — never modifies.
- Tier 02 beta after Tier 01 has been used on a real engagement sign + field. Closed beta to first engagement clients.
- v1.0 when Tier 02 has survived a full engagement without breaking deploy + rollback. Public open-source release with stable API and a real changelog.
No dates. We'll publish targets when there's something to point at. A real changelog starts the day Tier 01 ships.