Skip to content

README.md

Latest commit

 

History

History
94 lines (69 loc) · 3.96 KB

README.md

File metadata and controls

94 lines (69 loc) · 3.96 KB
Raw

comline

The command-line interface for Comline — build, validate, diff and generate code from Comline schemas.

Comline is in early development. The schema language and CLI surface may still change between versions.

Install

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

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

Quick start

comline new my-api          # scaffold a project
cd my-api
comline build               # compile + freeze version 0.0.1
comline generate            # write generated code for each configured target

Commands

Command What it does
comline new <name> [--git] Scaffold <name>/ with config.idp, comline.toml, src/main.ids and a .gitignore. --git also runs git init.
comline check Parse, resolve and validate every schema. No .comline/ writes, no version bump — safe for editors, hooks and CI.
comline build [--release] [--watch] Compile, validate, and freeze a new immutable version into .comline/. Prints the changelog and the version bump.
comline generate [--target <lang>] [--out <dir>] [--layout <tpl>] [--mode <m>] [--watch] Validate (no freeze), then write generated code. Output location/layout come from comline.toml [generate]; targets from there or config.idp.
comline diff <old> <new> Show the schema changes between two built versions. Each argument is a version (0.2.0), a commit hash, or HEAD (the default for <new>).
comline clean [--dry-run] Remove the generate output (the output root, or the individual files). Leaves .comline/ alone.
comline reset [--force] [--dry-run] Discard the version history: delete .comline/ and generated code. Asks for confirmation on a terminal; needs --force otherwise. No undo — the next build restarts at 0.0.1.
comline completions <shell> Print a shell completion script to stdout.

Global flags: --path <dir> to run outside the current directory, -v/-vv for more log detail, -q/--quiet to silence everything but errors.

See docs/cli.md for the full guide — every command and flag, the versioning model, output and exit codes, watch mode, and packaging.

Versioning model

Comline stores every build as an immutable commit in an append-only chain under .comline/ (content-addressable, git-inspired). Each build compares the new schemas against the previous version and bumps automatically:

  • major — a breaking change (removed/retyped field, removed variant, …)
  • minor — a new feature (added struct/enum/variant/field, …)
  • patch — a modification (field made optional, docstring change, …)

comline diff runs that same comparison between any two stored versions on demand.

Exit codes

code meaning
0 success
1 the command ran but failed
2 a precondition was not met (not a Comline project, nothing built yet, reset not confirmed) or a usage error

Development

cargo test
cargo fmt --check
cargo clippy --all-targets -- -D warnings

Man pages and completion scripts for all shells are generated into OUT_DIR (target/.../build/comline-*/out/{man,completions}/) on every build.

License

The comline CLI is licensed under the GNU General Public License v3.0 only (LICENSE or https://www.gnu.org/licenses/gpl-3.0.html) — it links comline-core and the code generators, which are GPL.

Copyleft covers the toolchain, not what you build with it. Running comline generate no more licenses your project than compiling it with GCC does; the code it emits is yours and links only comline-runtime (MPL-2.0). See design/licensing.md for the rationale and per-repo split.

Contribution

Unless you state otherwise, any contribution you submit for inclusion is licensed GPL-3.0-only, without additional terms.