CLI reference

Command Overview:

• trellis↴
• trellis list↴
• trellis graph↴
• trellis info↴
• trellis run↴
• trellis exec↴
• trellis changelog↴
• trellis changelog new↴
• trellis changelog check↴
• trellis version↴
• trellis version plan↴
• trellis version apply↴
• trellis init↴
• trellis new↴
• trellis release↴
• trellis release pr↴
• trellis release bootstrap↴
• trellis tag↴
• trellis tag plan↴
• trellis tag create↴
• trellis publish↴
• trellis lockfile↴
• trellis lockfile refresh↴
• trellis doctor↴
• trellis ci↴
• trellis ci matrix↴
• trellis ci outputs↴
• trellis ci tag-package↴
• trellis completions↴

trellis

A workspace CLI for Gleam monorepos: task fan-out, introspection, and release orchestration derived entirely from gleam.toml

Usage: trellis [OPTIONS] <COMMAND>

Subcommands:

• list — List packages in topological order (dependencies first)
• graph — Render the dependency graph
• info — Show details for one package
• run — Run a task across packages, graph-parallel by default
• exec — Run an arbitrary command in each package directory
• changelog — Changelog fragment management (see [tools.trellis.changelog])
• version — Plan and apply version bumps from unreleased changelog fragments
• init — Bootstrap a workspace: write a [tools.trellis] table at the repo root
• new — Scaffold a new package in the workspace
• release — Release orchestration
• tag — Compare package versions against git tags; create what’s missing
• publish — Publish packages to Hex, in dependency order, with path deps rewritten
• lockfile — Lockfile maintenance
• doctor — Validate workspace invariants; non-zero exit on any error
• ci — Structured output for CI
• completions — Print the shell snippet that enables tab-completion

Options:

• -C, --directory <DIR> — Run as if started in this directory

• --color <WHEN> — When to color output. auto follows the terminal, NO_COLOR, and CLICOLOR=0; the other two override that detection

  Default value: auto

  Possible values: auto, always, never

• -q, --quiet — Suppress normal-path output; JSON/report payloads and errors still print

• -v, --verbose — Trace every command trellis shells out to, on stderr

• --no-update-check — Don’t check whether a newer trellis release is available

  The check is also skipped in CI, when not attached to a terminal, and when TRELLIS_NO_UPDATE_CHECK or DO_NOT_TRACK is set.

trellis list

List packages in topological order (dependencies first)

Usage: trellis list [OPTIONS]

Options:

• --json — Emit JSON instead of name/lifecycle columns
• --since <REF> — Only packages owning files changed since this git ref
• --with-dependents — Add the reverse-dependency closure of the selection
• --releasable — Only packages whose release lifecycle is git_only or hex

trellis graph

Render the dependency graph

Usage: trellis graph [OPTIONS]

Options:

• --format <FORMAT>

  Default value: text

  Possible values: text, dot, mermaid, json

trellis info

Show details for one package

Usage: trellis info [OPTIONS] <PACKAGE>

Arguments:

• <PACKAGE>

Options:

• --json — Emit JSON instead of the text summary

trellis run

Run a task across packages, graph-parallel by default

Usage: trellis run [OPTIONS] <TASK> [PACKAGES]...

Arguments:

• <TASK> — Built-in (build, test, check, format, docs, deps, clean) or a [tools.trellis.tasks] entry
• <PACKAGES> — Packages to run in; all workspace packages when omitted

Options:

• --since <REF> — Only packages owning files changed since this git ref

• --with-dependents — Add the reverse-dependency closure of the selection

• --target <TARGET> — Gleam compile target; all runs the task once per target

  Possible values: erlang, javascript, all

• --strict — Treat warnings as errors (build)

• --check — Check instead of write (format)

• --serial — Run one package at a time, in dependency order

• --keep-going — Keep scheduling packages after a failure

• -j, --jobs <N> — Maximum concurrent packages (default: CPU count)

• --json — Emit the trellis.run/1 payload instead of the summary table; package output moves to stderr

trellis exec

Run an arbitrary command in each package directory

Usage: trellis exec [OPTIONS] [PACKAGES]... -- <COMMAND>...

Arguments:

• <PACKAGES> — Packages to run in; all workspace packages when omitted
• <COMMAND> — The command to run (after --)

Options:

• --since <REF> — Only packages owning files changed since this git ref
• --serial — Run one package at a time, in dependency order
• --keep-going — Keep scheduling packages after a failure
• -j, --jobs <N> — Maximum concurrent packages (default: CPU count)
• --json — Emit the trellis.exec/1 payload instead of the summary table; package output moves to stderr

trellis changelog

Changelog fragment management (see [tools.trellis.changelog])

Usage: trellis changelog <COMMAND>

Subcommands:

• new — Add an unreleased changelog fragment
• check — Verify changed packages have changelog fragments; non-zero exit if not

trellis changelog new

Add an unreleased changelog fragment

Usage: trellis changelog new [OPTIONS] --kind <KIND> --body <BODY>

Options:

• --package <PACKAGE> — The package the change belongs to (optional when the workspace has exactly one releasable package)
• --kind <KIND> — Change kind (see [tools.trellis.changelog] kinds; defaults include Added, Fixed, Breaking, …)
• --category <CATEGORY> — Change category, grouping entries above the kind headings (see [tools.trellis.changelog] categories; none are configured by default)
• --body <BODY> — The changelog entry text

trellis changelog check

Verify changed packages have changelog fragments; non-zero exit if not

Usage: trellis changelog check [OPTIONS] --base <BASE>

Options:

• --base <BASE> — Base ref of the change range

• --head <HEAD> — Head ref of the change range

  Default value: HEAD

• --format <FORMAT> — How to report: prose, the trellis.changelog_check/2 JSON payload (including a Markdown preview for a PR comment), or key=value lines for $GITHUB_OUTPUT

  Default value: text

  Possible values:

  • text
  • json: The trellis.changelog_check/2 payload
  • github: key=value lines for $GITHUB_OUTPUT, so a workflow can post, update, or delete a PR comment without a jq pipeline

• --strictness <STRICTNESS> — Override the workspace’s changelog.strictness for this run: fail on a missing entry, report it advisorily, or don’t check

  Possible values: warn, error, off

• --json — Deprecated alias for --format json

trellis version

Plan and apply version bumps from unreleased changelog fragments

Usage: trellis version <COMMAND>

Subcommands:

• plan — Dry-run: show what version apply would bump
• apply — Bump versions, render changelogs, patch manifest.toml locked versions

trellis version plan

Dry-run: show what version apply would bump

Usage: trellis version plan [OPTIONS]

Options:

• --bump <LEVEL|PKG=LEVEL> — Override the derived bump level, workspace-wide (--bump major) or for one package (--bump lat_core=major). Repeatable
• --set <PKG=VERSION> — Pin a package’s next version exactly (--set lat_core=1.0.0). Repeatable
• --pre <LABEL> — Cut a prerelease: --pre rc gives 1.0.0-rc.1, and again 1.0.0-rc.2. Fragments stay unreleased until the final version. --pre none promotes the current prerelease to its final version and consumes them
• --json — Emit JSON instead of text

trellis version apply

Bump versions, render changelogs, patch manifest.toml locked versions

Usage: trellis version apply [OPTIONS]

Options:

• --bump <LEVEL|PKG=LEVEL> — Override the derived bump level, workspace-wide (--bump major) or for one package (--bump lat_core=major). Repeatable
• --set <PKG=VERSION> — Pin a package’s next version exactly (--set lat_core=1.0.0). Repeatable
• --pre <LABEL> — Cut a prerelease: --pre rc gives 1.0.0-rc.1, and again 1.0.0-rc.2. Fragments stay unreleased until the final version. --pre none promotes the current prerelease to its final version and consumes them
• --json — Emit JSON listing every bump and patched lockfile

trellis init

Bootstrap a workspace: write a [tools.trellis] table at the repo root

Everything trellis can derive it derives, so the table this writes is nearly empty by design — its presence is what marks the workspace root. Members stay auto-discovered from git; the comments it leaves point at what can be configured. Refuses if the repository is already a trellis workspace, and finishes by running doctor.

Usage: trellis init

trellis new

Scaffold a new package in the workspace

Usage: trellis new [OPTIONS] <NAME>

Arguments:

• <NAME> — Package name (lowercase letters, digits, and _)

Options:

• --template <TEMPLATE> — Template to scaffold from

  Default value: lib

• --path <PATH> — Parent directory relative to the workspace root (derived from existing members when omitted)

trellis release

Release orchestration

Usage: trellis release <COMMAND>

Subcommands:

• pr — Create or update the release PR: version apply on a branch, push, open or refresh the PR via the GitHub API
• bootstrap — Reconcile tags against current manifest versions — no version bump, no unreleased changelog fragments required

trellis release pr

Create or update the release PR: version apply on a branch, push, open or refresh the PR via the GitHub API

Usage: trellis release pr [OPTIONS]

Options:

• --base <BASE> — Base branch the PR targets

  Default value: main

• --branch <BRANCH> — Branch the release commit is force-pushed to

  Default value: release/pending

trellis release bootstrap

Reconcile tags against current manifest versions — no version bump, no unreleased changelog fragments required

An alias for tag create, for adopting trellis on a repository that already has the package versions and changelogs it wants, but no tags yet.

Usage: trellis release bootstrap [OPTIONS]

Options:

• --push — Push each created tag to origin
• --github-release — Also create a GitHub Release per exact tag, with the matching CHANGELOG section as the body (implies –push; needs a GitHub token from GITHUB_TOKEN, GH_TOKEN, or a logged-in gh CLI)
• --dry-run — Report every tag/push/release action without doing anything (a conflicting tag still fails the command)

trellis tag

Compare package versions against git tags; create what’s missing

Usage: trellis tag <COMMAND>

Subcommands:

• plan — List releasable packages whose current version has no tag yet
• create — Create missing tags in topological order

trellis tag plan

List releasable packages whose current version has no tag yet

Usage: trellis tag plan [OPTIONS]

Options:

• --json — Emit JSON instead of text

trellis tag create

Create missing tags in topological order

Usage: trellis tag create [OPTIONS]

Options:

• --push — Push each created tag to origin
• --github-release — Also create a GitHub Release per exact tag, with the matching CHANGELOG section as the body (implies –push; needs a GitHub token from GITHUB_TOKEN, GH_TOKEN, or a logged-in gh CLI)
• --dry-run — Report every tag/push/release action without doing anything (a conflicting tag still fails the command)

trellis publish

Publish packages to Hex, in dependency order, with path deps rewritten

Usage: trellis publish [OPTIONS] [PACKAGE]

Arguments:

• <PACKAGE> — A single package to publish

Options:

• --tag <TAG> — Resolve a pushed tag (e.g. lat_core-v1.2.0) to its package
• --all-untagged — Every hex-lifecycle package whose version isn’t on Hex yet
• --dry-run — Show what would be published (and rewritten) without doing it

trellis lockfile

Lockfile maintenance

Usage: trellis lockfile <COMMAND>

Subcommands:

• refresh — Run gleam deps download, scoped to one package (with retry/backoff)

trellis lockfile refresh

Run gleam deps download, scoped to one package (with retry/backoff)

Usage: trellis lockfile refresh [OPTIONS]

Options:

• --package <PACKAGE> — Refresh only this package instead of the whole workspace

trellis doctor

Validate workspace invariants; non-zero exit on any error

Usage: trellis doctor [OPTIONS]

Options:

• --fix — Apply the mechanically-fixable findings (seed changelog stubs, patch stale locked versions), then re-report what remains

• --dry-run — List the fixes --fix would apply without writing anything

• --format <FORMAT> — How to report findings: prose, the trellis.doctor/1 JSON payload, or GitHub Actions annotations that land on the file in a PR

  Default value: text

  Possible values:

  • text
  • json: The trellis.doctor/1 payload
  • github: GitHub Actions workflow commands, so findings land on the file in the PR’s Files tab instead of in a log nobody expands

trellis ci

Structured output for CI

Usage: trellis ci <COMMAND>

Subcommands:

• matrix — Emit a GitHub Actions strategy matrix: {“include”:[{name,path,version},…]}
• outputs — Emit workspace facts as key=value lines for $GITHUB_OUTPUT
• tag-package — Resolve a pushed tag (e.g. $GITHUB_REF_NAME) to its package name

trellis ci matrix

Emit a GitHub Actions strategy matrix: {“include”:[{name,path,version},…]}

Usage: trellis ci matrix [OPTIONS]

Options:

• --since <REF> — Only packages affected by changes since this git ref (dependents included)
• --releasable — Only packages that participate in releases

trellis ci outputs

Emit workspace facts as key=value lines for $GITHUB_OUTPUT

Usage: trellis ci outputs

trellis ci tag-package

Resolve a pushed tag (e.g. $GITHUB_REF_NAME) to its package name

Usage: trellis ci tag-package [OPTIONS] <TAG>

Arguments:

• <TAG>

Options:

• --json — Emit JSON with the resolved package, version, and tag kind

trellis completions

Print the shell snippet that enables tab-completion

The snippet asks trellis for candidates on each tab-press, so completions offer real package and task names from the surrounding workspace and can never drift from the flags you have. Evaluate it on shell startup rather than saving it to a completions directory — it talks to trellis over an interface that changes between releases, so an eval stays in sync where a saved copy goes stale. For zsh, in ~/.zshrc after compinit:

eval “$(trellis completions zsh)”

Usage: trellis completions <SHELL>

Arguments:

• <SHELL> — Shell to emit a registration snippet for

  Possible values: bash, elvish, fish, powershell, zsh