Skip to content

Latest commit

 

History

History
925 lines (738 loc) · 37.6 KB

cli.md

File metadata and controls

925 lines (738 loc) · 37.6 KB

comline CLI guide

comline is the command-line interface to Comline. It drives the everyday workflow around Comline schemas: scaffold a project, validate it, freeze immutable versions, compare versions, and generate code — all on top of comline-core.

This is the long-form reference. For a two-minute tour see the README.

Overview

A Comline project is a directory with a package manifest (config.idp) and one or more schema files (src/**/*.ids), optionally a comline.toml for code-generation output. Running a command takes those inputs through:

parse → resolve imports → validate → (freeze into .comline/) → (generate code)

check stops after validation. build adds the freeze step and records a new version. generation stops after validation too — it does not freeze — and writes generated code per comline.toml. diff reads two already-frozen versions and reports what changed between them.

Installation

comline is not published to crates.io yet. Build it from source:

git clone https://github.com/ComlineProject/cli
cd cli
cargo install --path .

This installs the comline binary into ~/.cargo/bin. Man pages and shell completions are generated during the build — see Shell completions and man pages.

Project layout

comline new my-api creates:

my-api/
├── config.idp        # package manifest: name, spec version, code_generation targets
├── comline.toml      # where `generation` writes code and how (all-commented by default)
├── src/
│   └── main.ids      # a sample enum + struct to build on
└── .gitignore        # ignores .comline/deps-cache/

config.idp starts as:

congregation my_api
specification_version = 1

code_generation = {
    languages = {
        rust#1.85.0 = {}
    }
}

The declared languages are a capability list only — a bare language#lang_version. Which of them to generate, where, and for which package versions is set in comline.toml (below).

The directory keeps the name you gave; the congregation name is that name reduced to a valid Comline identifier (letters, digits and _), so comline new my-api produces the directory my-api/ with congregation my_api.

After the first comline build, a .comline/ directory appears next to config.idp. It holds the content-addressable store (objects/) and the version ref (refs/heads/main). It is the package's version history, so commit it. Only .comline/deps-cache/, where git dependencies are fetched, is a local cache; the scaffold's .gitignore ignores that and nothing else.

Versioning model

Comline stores every build as an immutable commit in an append-only chain under .comline/, git-inspired and content-addressed. There are no branches and history is never rewritten, so any past version stays reproducible.

Each build compares the new schemas against the previous version and bumps the package version automatically, by the largest change it finds:

bump when examples
major a breaking change removed struct/enum/field/variant/function, changed field type, added a required field
minor a new feature added struct/enum/protocol/error, added a variant, added an optional field, new schema file
patch a modification field made optional, docstring-only change

The first build is version 0.1.0-dev.1. A build with no schema changes keeps the current version and does not add a commit. comline diff runs this same comparison between any two stored versions on demand.

The chain in .comline/ is the only copy of this history — there is no publish step yet. comline generation clean does not touch it; only comline reset discards it, after which the next build starts over at 0.1.0-dev.1.

Commands

Every command accepts the global flags. Run comline <cmd> --help for the authoritative synopsis.

comline new

comline new <name> [--git]

Scaffold <name>/ (see Project layout). Fails if the directory already exists.

  • --git — also run git init in the new project. If git is missing or fails, the project is still created and a warning is printed.
comline new my-api
comline new my-api --git

comline deps add

comline deps add <name> <dir> [--no-hash]
comline deps add <name> --git <uri> --commit <sha> --version <version> [--no-hash]

Declare another Comline package as a dependency, imported under <name>: use <name>::models::Thing. It is resolved first, the way check resolves it, so an entry that wouldn't resolve is never written:

  • <dir> — a package on disk, relative to this package's directory (written to config.idp as given);
  • --git <uri> --commit <sha> --version <version> — a commit of a git repository, fetched into .comline/deps-cache/ with the git binary. --version is the version that commit stands for.

The entry goes into config.idp's dependencies block, created at the end of the file if there isn't one, in the file's own indentation; every other line is left as written. Its hash is pinned to the content just compiled, so if the dependency changes later, check and build fail until the pin is updated.

  • --no-hash — don't pin the hash (say, a path dependency still being worked on).
comline deps add shared_types ../shared-types
comline deps add net --git https://github.com/acme/net --commit 4f2c9e1 --version 1.2.0

Exit 0 once added, 1 if the dependency doesn't resolve or can't be added (the name is already declared, isn't an identifier, or is already one of this package's own namespaces), 2 if the directory is not a Comline project.

comline deps pin

comline deps pin <name> [--commit <sha> --version <version>] [--accept-unverified]

Pin a dependency's hash to the content it has now. For a dependency that changed on purpose: check and build fail on the old pin (hash mismatch) until it's updated. The dependency is resolved first, the way deps add resolves it (a git pin is fetched into .comline/deps-cache/, then compiled), so a dependency that doesn't resolve is never pinned. Only its entry in config.idp changes; every other line is left as written. An entry written without a hash (deps add --no-hash) gains one.

The old and new hash are printed. If they're the same, it says so and writes nothing.

  • --commit <sha> --version <version> — move a git dependency to another commit in the same step (both together, git dependencies only).
  • --accept-unverified — if the new content gives up more through @unverified than the entry already accepts, what it gives up is shown and, on a terminal, you are asked to accept it; without a terminal this flag accepts it. The same steps as deps add. Nothing is written unless it's accepted.
comline deps pin shared_types
comline deps pin net --commit 9b1d3e7 --version 1.3.0
$ comline --plain deps pin shared_types
Resolving shared_types
Pinned shared_types in config.idp
  was: blake3:4b2c2573d7022c99ff9c66922673441b9b4cc36b79e5e6bdfee2251cf3ad10d1
  now: blake3:b9684859cabadf2f66d72f47811581ec4fdbd2821816008d3e85bf550f3fae7a

Exit 0 once pinned or already pinned, 1 if the dependency isn't declared, doesn't resolve or can't be written, 2 if it needs accepting and there's no terminal and no flag, or the directory is not a Comline project.

comline deps list

comline deps list [--json]

One line per dependency in config.idp: its name, where it comes from (a path, or a git URI at a short commit and its version), what its hash is pinned to (unpinned if there is none), and what accept_unverified accepts of it, if anything.

$ comline --plain deps list
billing  path ../billing                                  blake3:4b2c2573d702  accepts Billing (schema agreement and encoding agreement)
net      git https://github.com/acme/net@9b1d3e7 (1.3.0)  blake3:d476bafdea0f
scratch  path ../scratch                                  unpinned

It only reads config.idp: nothing is resolved or fetched, so it never uses the network, and nothing is written, .comline/ included. What it shows is what the file says, not whether the dependency still matches it (that's check).

--json prints the same as { "dependencies": [...] } on stdout, one object per dependency with the full values: name, source ({ "kind": "path", "path" } or { "kind": "git", "uri", "commit", "version" }), hash (null if unpinned), and accept_unverified (each accepted protocol with its guarantees, as config.idp names them). With none declared the text report is empty and the JSON's list is [].

Exit 0, or 2 if the directory is not a Comline project.

comline deps remove

comline deps remove <name> [--dry-run]

Take <name>'s entry out of config.idp's dependencies block. Only that entry goes; every other line is left as written.

If a schema still imports it (use <name>::...), it isn't removed: the error lists each use by file and line, and nothing is written, --dry-run or not.

  • --dry-run — show the entry that would be removed without writing anything.
comline deps remove shared_types
comline deps remove shared_types --dry-run
$ comline --plain deps remove shared
error: can't remove `shared`: 1 schema statement still imports it:
  src/holder.ids:1  use shared::models::Thing

remove or change those first; config.idp is unchanged

A name that isn't declared is an error that lists the ones that are. Exit 0 once removed, 1 if it's still imported, isn't declared or can't be removed, 2 if the directory is not a Comline project.

comline check

comline check

Parse, resolve and validate every schema and the package config, reporting the first error found. It writes nothing to .comline/ (beyond fetching git dependencies into .comline/deps-cache/) and does not bump the version — safe to run from editors, pre-commit hooks and CI lint steps.

comline check
comline --path ./services/users check

Exit 0 if valid, 1 if a schema or the config is invalid, 2 if the directory is not a Comline project.

comline inspect

comline inspect [--json]

What each protocol speaks on the wire, and which guarantees it keeps. Like check, it compiles the package and writes nothing to .comline/.

For each protocol, a short header names the format, framing and handshake it resolves to, with their parameters and where each came from:

Source Meaning
from @framing / from @handshake the protocol's own annotation
from config.idp ... the package's wire.format, wire.framing or handshake
core's default nothing named one: packed@1, datagram@3, comline@2 (comline@1 on any framing but datagram@3)
JSON-RPC's format the framing implies a format (JSON-RPC's is JSON, and the line names the framing by its title) and the package names no format

Then one row per guarantee (schema agreement, encoding agreement, encoding conformance, version honesty), held or given up. A given-up row says why, and whether it has been accepted. A dependency's protocol is accepted by this package's accept_unverified. Who accepts this package's own protocols isn't known here: each consumer does that in its own config.idp. A protocol's @unverified reason is in its header.

$ comline --plain inspect
protocol api::Legacy (shop)
  format     json@1                   JSON-RPC's format
  framing    jsonrpc (method_names = qualified) from @framing
  handshake  none                     from @handshake
  unverified "the 2009 gateway can't run a handshake"

  schema agreement       given up
      because handshake `none`
      acceptance: up to each consumer's config.idp
  encoding agreement     given up
      because handshake `none`
      acceptance: up to each consumer's config.idp
  encoding conformance   held
  version honesty        held

The report goes to stdout. --json prints the same as JSON, as { "protocols": [...] }, with each choice's source given as annotation, package_default, core_default or framing. Each guarantee's acceptance is { "state": "not_needed" | "unknown" | "not_accepted" }, or { "state": "accepted", "by": "<package>" }.

A protocol's compatibility facts (its line, version and shape hash) aren't shown, because they aren't built yet (core#119).

Exit 0 on success, 1 if a schema or the config is invalid, 2 if the directory is not a Comline project.

comline build

comline build [--watch] [--reconcile <hash>]

Compile and validate every schema, then freeze the result into .comline/, bumping the version per the versioning model. Prints the version change, a grouped changelog, and the bump that was applied.

  • --watch — rebuild on change; see Watch mode.
  • --reconcile <hash> — for a Git merge whose conflict on .comline/refs/heads/main was resolved by picking one side: puts the dropped side's head (a full commit hash) back beside the current one, then builds, so the build joins the two lines. Refused for a hash that isn't a commit in .comline/objects.

When .comline/refs/heads/main holds two heads (a Git merge left it conflicted, or --reconcile), the build reconciles them and says so: which head the line continued from and which one it recorded as the second parent.

Every string and list needs a maximum (bounds on types). A project written before bounds fails with one bounds::unbounded error per position; the build then says how many there are and shows the settings = { bounds = { … } } block that gives the package defaults (bounds.string.max, bounds.array.max) in config.idp. On a terminal it offers to add that block, with maxima you type in; it never picks them.

comline build
comline build --watch
comline build --reconcile 3f9a…  # the full 64-character hash

comline generation

comline generation [--target <lang>] [--out <dir>] [--layout <template>] [--mode <mode>] [--external-std] [--watch]
comline generation clean [--dry-run] [--target <lang>]

gen is short for generation.

Validate the project, then write generated code for each target. Unlike build, this does not freeze a version or write to .comline/ — it stops after validation.

Wire numbers. Protocols on datagram@3 or comline@2 (the defaults) need the package's facts: each protocol's and function's wire number, its line and its "since" versions. When the working tree is what the last build froze, generation uses that build's facts. Otherwise it works them out as the next comline build would, against the last release and every retired number, without writing anything. A package that was never built generates too. The numbers stay provisional until comline release, as a build's are.

Targets come from [[generate.target]] in comline.toml; if that file lists none, from code_generation.languages in config.idp.

Where the code goes is set in comline.toml's [generate] table:

[generate]
out              = "generated"                            # output root, relative to comline.toml
layout           = "{{language}}/{{namespace}}.{{ext}}"   # path of each file under the root
mode             = "code"                                 # code (loose source) | lib (a buildable package)
external_std     = false                                  # reference comline_std instead of inlining it (rust only)
package_versions = "latest"                               # latest | all | ["0.3.0", "0.4.0"]

# optional, one per target you want to pin or override:
[[generate.target]]
language = "rust"
out      = "src/generated"

comline.toml is committed, consumer-owned, and never frozen. With no comline.toml (or an all-commented one), the defaults above apply. Layout variables: {{language}}, {{namespace}} (/-joined), {{ext}}, {{lang_version}}, {{spec_version}}, {{package_version}}.

Editor support. comline.toml has a JSON Schema, generated from the same types comline generation parses it with, at https://comlineproject.github.io/docs/schemas/comline-toml/0.x.json. A comline new project's comline.toml starts with a line naming it:

#:schema https://comlineproject.github.io/docs/schemas/comline-toml/0.x.json

It's a TOML comment, so comline ignores it; editors using Taplo (Even Better TOML in VS Code) read it, and complete keys, describe them, and flag an unknown key or a wrong value (mode = "dylib") as you type. Add the line to an existing comline.toml to get the same.

layout only applies to code mode. A lib-mode target ignores it entirely (comline generation warns if you set one) and always writes the crate's fixed internal shape (Cargo.toml, src/lib.rs, …) at <out>/<language>/ — unless the target sets flatten = true, which writes it straight into out instead:

[[generate.target]]
language = "rust"
mode     = "lib"
out      = "../my-rust-crate/"
flatten  = true   # crate lands at out/ directly, not out/rust/

flatten only means something for lib/dylib targets with their own out — flattening a shared out across several lib targets would land two crates in the same directory.

External generators. A target can use a generator outside this binary:

[[generate.target]]
generator = "tools/comline-gen-go.wasm"   # or a native executable
language  = "go"                          # optional if the generator offers one language
timeout   = 120                           # seconds per call, default 60

generator is a path, relative to comline.toml's directory. The generator speaks the generator protocol: one CBOR request on stdin, one CBOR response on stdout. comline asks it to describe itself first, and refuses one whose protocol version or IR format it doesn't share, naming both sides, or one that doesn't offer the target's language at its version. language picks among the languages it offers and must still be one config.idp declares; lang_version applies as for a built-in.

  • A .wasm runs under wasmtime (cargo feature gen-wasm, on by default), sandboxed: no preopened directories, no environment variables, no network, no arguments beyond argv[0], and at most 1 GiB of memory.
  • Anything else runs as a native process with an empty environment. It isn't sandboxed: run only executables you trust.
  • Either is stopped after timeout seconds, and refused if it writes more than 256 MiB to stdout or generates more than 256 MiB of files. Its stderr is shown prefixed with its file name, up to 64 KiB.
  • Every path in its response must be relative and normalized: no .. or . components, no absolute paths, no drive or UNC prefixes (:, \), no empty components, no NUL. A response with any bad path is refused whole, and nothing from it is written.

The built-in generators answer the same protocol in process, so their output goes through the same checks.

Which versions. package_versions = "latest" (the default) generates the working tree — no .comline/ read. "all" generates every committed version in the CAS chain; ["0.3.0", "0.4.0"] (versions or commit hashes) generates just those. Anything but latest requires the project to have been built at least once, and — because more than one version would otherwise write to the same paths — the layout must contain {{package_version}}. For latest, {{package_version}} is the last committed version (empty if never built).

  • --target <lang> — only this language (case-insensitive). Errors if nothing matches.
  • --out <dir> / --layout <template> / --mode <mode> / --external-std — override one target's [generate] values. When more than one target is configured they require --target (otherwise it is ambiguous which they apply to).
  • COMLINE_GENERATE_OUT / COMLINE_GENERATE_LAYOUT / COMLINE_GENERATE_MODE / COMLINE_GENERATE_EXTERNAL_STD — the same overrides from the environment, sitting just below the flags but applied to every target (handy in CI). A flag still wins for its target.
  • --watch — regenerate on change; see Watch mode.

external_std (Rust only). When on, std is referenced as its own comline_std crate (a git dependency lib mode adds to the generated Cargo.toml automatically) instead of being re-emitted into the output on every run — a reference qualifies to comline_std::http::Request instead of a locally-inlined crate::std::http::Request. code mode has no manifest to edit on your behalf, so a file that ends up referencing it carries a comment naming the dependency line to add by hand. Default false (inlined, unchanged).

Currently rust and typescript are the generators; code mode is implemented for both and lib mode for rust. dylib, and lib for other languages, fail with a clear message.

comline generation
comline generation --target rust --out ./bindings
comline -p ./schemas generation --target rust
• Generating code (in schemas/)
  ⚙️  language: rust, version: 1.85.0
       main.ids → generated/rust/main.rs
       other.ids → generated/rust/other.rs
✓ Generated 2 file(s)

The working directory is named on the header; each line under a target maps a source schema to the file written for it (--plain uses ->).

comline generation clean

comline generation clean [--dry-run] [--target <lang>]

Remove what generation wrote — the whole output root when it is a dedicated directory (e.g. generated/), otherwise just the individual generated files. Resolved the same way generation resolves output (comline.toml [generate], else config.idp's declared languages).

Does not touch .comline/. Generated code is regenerable; the version history is not — comline reset is the command for that.

  • --dry-run — list what would be removed without deleting anything.
  • --target <lang>, -t — only remove that language's output; a language no target matches is an error, as it is for generation --target.

Needs the project to compile to know what generation would have written; if it does not, there is nothing to clean.

comline generation clean --dry-run
comline generation clean
comline generation clean --target rust

comline diff

comline diff <old> [<new>]

Compare two frozen versions from .comline/ and print the breaking changes, new features and modifications between them — the same report build shows, on demand. <new> defaults to HEAD.

Each argument is one of:

  • a version string, e.g. 0.2.0
  • a commit hash (full, or a prefix of 4+ characters)
  • HEAD — the latest build
comline diff 0.1.0 0.2.0
comline diff 0.1.0            # 0.1.0 against HEAD
comline diff 0.1.0-dev.1 HEAD

Fails with exit 2 if the project has never been built, and exit 1 if an argument matches no stored version (the error lists the versions that exist).

comline doc

comline doc [--out <dir>] [--version <v>] [--changelog-from <v>] [--format <f>[,<f>...]] [--open]
comline doc open [<format>] [--out <dir>]

Write the package's documentation for every version: each release, each dev build and the unreleased working state (when it differs from the last build). Nothing is written to .comline/.

Each format lands in <out>/<format>/, with one folder per version: 0.2.0/, 0.3.0-dev.2/, and unreleased/ for the working tree. Each version carries the changelog from the version before it, computed by core's comline diff rules.

  • Pages (markdown, the default, rendered by the official renderer linked into comline): per version, index.md (the package, its //! header, its modules), one page per module (types::user is types/user.md) with its //! header and every unit with its /// docs, fields, arguments and each protocol's wire summary, changelog.md, and nav.yml, a nav for mkdocs or zensical. <out>/markdown/index.md lists the versions. Switching versions on a published site is left to site tooling, such as mike for mkdocs.
  • html writes a self-contained static site per version, rendered by the official HTML renderer, also linked in: index.html, one page per module (types/user.html), changelog.html, style.css and search.js. It has the same content as the Markdown pages, plus a sidebar of modules and units, a search box over the units, a version picker in the header, and light and dark themes that follow the OS setting. The picker opens the same page and unit in the chosen version, or that version's index with a note when it has no such page. At <out>/html/, index.html points at the latest version (the newest release, else the newest dev build), and compare.html compares versions: two show what changed between them, grouped by unit and labelled major, minor or patch; more show a grid of every unit and member per version. The labels come from the changelogs core computed between each version and the one before it; the page never judges a change itself. Nothing loads from the network and every link is relative, so the site opens straight from disk or from any static host.
  • json writes each version's documentation model, model.json, in the shape of core's schemas/doc-model.json, and <out>/json/index.json listing the versions.
Flag Default Meaning
--out <dir> [doc] out, else docs/api where to write, relative to the project
--version <v> every version document only this built version (a version string, a commit hash, or HEAD), into <out>/<format>/<v>/
--changelog-from <v> [doc] changelog_from with --version: add what changed from built version <v>
--format <f> [doc] formats, else markdown markdown, html, json, or another id the [doc] renderer offers; repeat it or separate with commas
--open off after rendering, open the first format's index (see comline doc open); with --version, that version's own index

A module's summary table lists each unit with its summary, then a Type column (a constant's type, a type alias's target; linked where it can be) and a Value column (a constant's value), each only when some unit in the module has one. Structs, enums, protocols and the like leave both cells empty.

comline doc open [<format>]

Open the generated documentation with the system's default handler: <out>/<format>/index.html, index.md or index.json, for html, markdown or json. --out is read as comline doc reads it.

  • With no <format>, html if it is among [doc] formats or already rendered (say by comline doc --format html), else the first configured format.
  • If that file isn't there, the format is rendered first, exactly as comline doc --format <format> would. If it is, it is opened as it is, without re-rendering; the command says so in one line and how to refresh (comline doc --format <format>).
  • HTML opens in the browser named by $BROWSER, else the system's default (xdg-open, open, or the Windows shell); Markdown and JSON open in whatever the system associates with the file.
  • It prints the absolute path it opens. With no display, or when nothing opens, it prints that path and a hint instead, and exits 0.

Caching. A built version never changes, so its folder is kept between runs. <out>/<format>/.comline-doc.json records the key each folder was rendered with: its commit, the commit of the version before it, the renderer and its version, the model version and the links. A built-in renderer's version carries a content hash of its sources and assets (0.1.0+<hash>), so a comline with a changed renderer re-renders every folder; an external renderer is keyed by its file's hash. A run re-renders only the folders whose key changed, which is the unreleased state and new versions, and removes the folders of versions no longer listed.

A built version keeps no source, so its protocols have no wire summary, and a version built before headers were stored has no //! headers. Its pages say so in a note.

comline.toml's [doc] table:

[doc]
out = "docs/api"
formats = ["html", "markdown", "json"]
versions = { last = 5 }                  # or "all" (the default), { since = "0.3.0" }, { releases_only = true }
renderer = "renderers/my-renderer.wasm"  # optional: an external renderer
timeout = 60                             # seconds per call to `renderer`
links = { std = "https://comlineproject.github.io/docs/reference/package/schema/std/" }
changelog_from = "0.1.0"                 # with --version only
  • versions trims the list. last = N keeps the newest N (the unreleased state counts as one), since keeps that version and newer, and releases_only keeps releases alone (no dev builds and no unreleased state). They combine, applied in that reverse order: releases_only, then since, then last.
  • renderer is run exactly like an external generator: a .wasm under wasmtime with no filesystem, environment or network, a native executable with an empty environment, the same limits and path checks. It must list the format in its Describe answer's renderers. One that doesn't render a site index (sites in its Describe answer) still renders every version's folder.
  • links maps a dependency (or std) to the base URL of its documentation. A type from it links to <base>/<module>/#<anchor>; a dependency not listed is plain text.

comline new adds docs/api/html/ to .gitignore.

comline doc
comline doc --format html,markdown
comline doc --version 0.2.0 --changelog-from 0.1.0
comline doc --format html --out site
comline doc --format json
comline doc --open
comline doc open
comline doc open markdown

comline conformance

comline conformance --impl "<command line>" [--encoding <name>]... [--corpus <dir>] [--timeout <secs>]

Run an implementation of an encoding against its vectors, the way the official runtimes are proven against the official corpus. A package that declares an encoding under encodings in config.idp ships its vectors beside its profile: the profile's path with .json replaced by .vectors.json.

encodings = {
    "com.acme.lines@1" = { kind = "framing" profile = "profiles/lines.json" }
}
profiles/lines.json           the profile: facts, each naming the cases that prove it
profiles/lines.vectors.json   the vectors: {"feature": ..., "cases": [...]}

The vectors file and the profile are in the conformance corpus's case format, a public spec (early days, versioned in its VERSION), documented in ComlineProject/specification's README. Every case in the file is run, and each profile fact's proven_by names cases in it.

The implementation is a process speaking the conformance ops protocol, as comline-reference does: newline-delimited JSON requests on stdin, one reply line each on stdout, exit 0 when stdin ends. Its version reply lists the encodings it implements under formats and framings. It runs once, with every question sent up front (a case's questions never depend on the answers), under the same rules as an external generator: a cleared environment, a time limit (--timeout, 60 seconds by default) and a capped stdout; its stderr is shown, prefixed with its name. The command line is split on whitespace (no shell quoting); a bare program name is looked up on PATH.

The report, on stderr, gives per encoding the cases that pass, each profile fact as proven or not (and why), and each failed case, an encode with a byte diff:

com.acme.lines@1 (framing): 4/5 case(s) pass
  proven  calls: by_name
error unproven  errors: by_ordinal — case `lines/error` failed
error lines/error failed: encodes wrong:
      expected: 455252203720322036653666
           got: 455252203720332036653666
                            ^^ byte 6 differs

A failed case, a case the implementation reports as not implemented, or an unproven fact makes the exit code 1.

  • --impl <command line>: the implementation.
  • --encoding <name>: only this encoding (repeatable). Default: every encoding the package declares.
  • --corpus <dir>: run a copy of ComlineProject/specification (profiles/<name>.json, vectors/*.json) instead of the package's declarations: the official encodings (packed@1, datagram@2, ...), whose vectors live there. Each encoding runs every case of the features its profile's facts name.
  • --timeout <secs>: how long the implementation may take for all the cases together.
comline conformance --impl ./target/release/acme-lines-conformance
comline conformance --impl comline-reference --corpus ../specification --encoding packed@1

comline reset

comline reset [--force] [--dry-run]

Delete .comline/ — every frozen version and the commit chain — and generated code. This cannot be undone, and since nothing else holds the history, the next build starts over at 0.1.0-dev.1.

Guarded:

  • on a terminal, you are shown how many versions will be lost and must type reset to proceed;
  • without a terminal (CI, scripts) it refuses with exit 2 unless --force is given.
  • --dry-run — list what would be removed, and the history that would be lost, without deleting anything. No confirmation needed.
comline reset --dry-run
comline reset            # asks for confirmation
comline reset --force    # scripted

comline completions

comline completions <shell>

Print a completion script for <shell> to stdout. Supported: bash, zsh, fish, powershell, elvish.

comline completions bash > /etc/bash_completion.d/comline
comline completions fish > ~/.config/fish/completions/comline.fish
comline completions zsh  > ~/.zfunc/_comline

Global flags

flag effect
-p, --path <DIR> Run against <DIR> instead of the current directory. Headers echo it back (Building project (in <DIR>/)).
-v, -vv, -vvv Raise log verbosity. Default shows only warnings and errors from comline-core; -v adds info, -vv debug, -vvv trace.
-q, --quiet Silence all progress output; only errors are printed. Conflicts with -v.
--plain Plain output: no color, no leading symbols (• / ✓), no emoji in the changelog, no spinner. For log files and CI.

RUST_LOG overrides the verbosity flags entirely if set (standard tracing_subscriber syntax, e.g. RUST_LOG=comline_core=debug).

Output and exit codes

  • stderr carries all human-facing output: progress steps, the changelog, warnings, errors, and -v diagnostics.
  • stdout is reserved for machine-readable payloads. Today only comline completions writes there, so comline completions fish | source and similar pipelines are clean.
  • Color is applied through anstream: it is stripped automatically when stderr is not a terminal or when NO_COLOR is set. --plain also drops the leading symbols and changelog emoji, not just color.
  • The progress spinner is shown only on an interactive terminal, and is suppressed under -v (so it doesn't fight the log output), --quiet and --plain.

Exit codes are stable for scripting and CI:

code meaning
0 success
1 the command ran but failed — invalid schema, unresolved diff argument, a generator or filesystem error
2 a precondition was not met — the directory is not a Comline project, nothing has been built yet, or a destructive command (reset) was not confirmed. clap also exits 2 for usage errors.
if ! comline check --quiet; then
  echo "schemas are invalid" >&2
  exit 1
fi

Watch mode

comline build --watch and comline generation --watch run the action once, then re-run it whenever a file under src/ changes or config.idp / comline.toml is modified (300 ms debounce). A failing run is reported but does not stop the loop — fix the error and save again. Press Ctrl-C to exit.

comline generation --watch --target rust

Shell completions and man pages

Two paths, for two audiences:

  • Users: comline completions <shell> (above) prints a script on demand.

  • Packagers: every build also writes, into the crate's OUT_DIR:

    • man/comline.1 and man/comline-<subcommand>.1
    • completions/comline.{bash,zsh,fish,elv} and _comline for PowerShell

    After cargo build, find them under target/<profile>/build/comline-*/out/{man,completions}/.

Editor and pre-commit integration

Use comline check — it validates without writing to .comline/ or bumping the version, so it is safe to run on every save or in a hook.

# .git/hooks/pre-commit
#!/bin/sh
exec comline check --quiet