Repository navigation
docs(reference): add CLI command reference and config/spec pages - #863
Conversation
📝 WalkthroughWalkthroughThe documentation reorganizes CLI references around ChangesCLI and command references
Schema and supporting documentation
Estimated code review effort: 3 (Moderate) | ~25 minutes Possibly related issues
Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
Comment |
Add the per-binary CLI reference (min, mip, minimald, minvmd) and the reference manifest, and revise the config/spec pages: minimal.toml, tasks, build specs, sandbox operations, the cli overview, and the harness-specs -> stack-specs rename. Drop a stale "known issues" note in the mip reference whose cited bugs (dump --stacks and patched-build --remote-addr) were since fixed and their issues closed. The loadouts reference page follows in a separate PR. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
9b47593 to
d6e7d25
Compare
|
@macroscope-app review |
|
Manual reviews triggered for commit All prior checks · these links stay valid even if you push more commits. |
|
Review in progress. Results will be posted as check runs when complete. |
|
@coderabbitai ignore |
✅ Action performedReviews paused. |
ApprovabilityVerdict: Would Approve Documentation-only changes adding CLI reference pages and updating existing docs. No runtime code changes. Open comments are minor doc accuracy issues that don't affect runtime behavior. Macroscope would have approved this PR. Enable approvability here. |
…mpt, remove em-dashes Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 8
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/reference/cli-min.md`:
- Around line 8-11: Update the introductory description of the min CLI to state
that most commands automatically start minimald when it is not running, while
explicitly identifying the bug command as an exception. Keep the existing daemon
and session-management context unchanged.
- Line 30: Add language identifiers to every fenced code example in
docs/reference/cli-min.md, including the listed locations, using the appropriate
identifier such as console or shell so all fences satisfy markdownlint MD040.
- Around line 131-136: Update the environment-variable redaction behavior
described in the CLI documentation so sensitive-shaped names always take
precedence over the verbatim allowlist, including MINIMAL_*, MINVMD_*, and
MINIMALD_* variables. Restrict those prefixes to explicitly known-safe names or
state that sensitive-name filtering is applied after allowlist matching,
ensuring values such as MINIMAL_API_TOKEN are recorded by name only.
In `@docs/reference/cli-minimald.md`:
- Line 29: Add the console or shell language identifier to both fenced command
blocks in the CLI documentation, including the fences at the referenced
locations, so they comply with markdownlint MD040.
- Around line 21-22: Update the defaults documented for the --minimal-state-dir
and --minimal-cache-dir options to reference XDG_STATE_HOME and XDG_CACHE_HOME
respectively, keeping the existing option descriptions unchanged.
In `@docs/reference/cli-minvmd.md`:
- Line 26: Add a language identifier to every fenced command block in the CLI
documentation, including the blocks at all referenced locations. Use console or
shell consistently so markdownlint-cli2 MD040 passes.
In `@docs/reference/cli-mip.md`:
- Line 34: Add a console or shell language identifier to every fenced command
block in cli-mip.md, including the listed occurrences, while leaving the command
content unchanged.
In `@docs/reference/cli.md`:
- Around line 41-45: Update the “In-sandbox helper commands” overview in cli.md
to include build, test, and patched-pkg alongside add, search, check, and run,
or revise the wording to clearly indicate the listed commands are only examples;
keep the link to sandbox operations intact.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 93061e2b-d505-4a50-add4-30b1a3eda0bc
📒 Files selected for processing (12)
docs/reference/build-specs.mddocs/reference/cli-min.mddocs/reference/cli-minimald.mddocs/reference/cli-minvmd.mddocs/reference/cli-mip.mddocs/reference/cli.mddocs/reference/linux-host-setup.mddocs/reference/manifest.jsondocs/reference/minimal-dot-toml.mddocs/reference/sandbox-operations.mddocs/reference/stack-specs.mddocs/reference/tasks.md
…acies Remove commands that are feature-gated or not yet ready to expose, and correct several inaccuracies against the source: - min: drop the session policy, login, and feature-gated mesh/ssh-forward sections - min: note that most commands auto-start the daemon while bug does not, and that the daemon runs inside the minvmd microVM host on macOS - min/mip: add requires at least one package, so show <PACKAGES>... - minimald: default state/cache dirs are $XDG_STATE_HOME / $XDG_CACHE_HOME, not $XDG_*_DIR; drop the not-yet-exposed --num-parallel-builds flag - minvmd: document the run "start" alias and distinguish boot from run Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
|
||
| # `mip` - package/build CLI | ||
|
|
||
| `mip` is the Minimal package/build CLI. It reads a project's |
There was a problem hiding this comment.
Should probably mention that mip stands for "Minimal in-process", it only works on Linux, and its meant for advanced users only
There was a problem hiding this comment.
Done — cli-mip.md now opens with "mip (short for 'Minimal in-process')" plus a callout that it's Linux-only and for advanced users driving the package/build plane directly, pointing readers to the min session CLI. 31995e8
De-emphasize `mip` across the CLI reference: `min` is the primary surface, and `mip` is marked as the advanced, Linux-only package/build CLI (with its "Minimal in-process" name spelled out). Correct the in-sandbox `min add` flags: `--session` records packages in the `[session]` list in `minimal.toml`, and drop `--task`, which is not available in session sandboxes. Simplify the `--gvproxy-bin` description. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Replace the removed --minvmd flag with --provider local-minvmd, make attach's
SESSION optional with its resolution rules and the min-run-only exec channel,
list the real autostart exceptions, correct provider directory names, drop
dead known-issue links (the minvmd --timeout one is fixed on main), document
bare min and --no-input, and regenerate the help SHAs against main. Add the
missing [session] section (plus [params], [cache], [stdlib]) to the
minimal.toml reference, drop the phantom ty alias, retarget the dead
harnesses concept link, and rename the {#harness} anchor to {#stack}. Fix
tasks.md's invalid multi-line inline tables, document the echo action, and
correct alias directions. Scope sandbox-operations add semantics per backend
(session no-flag records in [session] packages). Cover the
max_user_namespaces preflight case in linux-host-setup. Quote colon-bearing
frontmatter descriptions across the reference set.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 5
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
docs/reference/minimal-dot-toml.md (1)
212-214: 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick winInclude the
env_varsalias in the raw-file validation rule.The preceding field definition documents
env_varsas an alias forvars, but this rejection rule mentions onlyvars. State that bothvarsandenv_varsare invalid forraw-fileoutputs.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/reference/minimal-dot-toml.md` around lines 212 - 214, Update the raw-file validation rule in the documentation to explicitly list both vars and its env_vars alias as invalid oci-image-only fields, while preserving the existing entrypoint, cmd, and path restrictions.docs/reference/linux-host-setup.md (1)
64-72: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick winDo not state that installing the profile does not weaken the host.
The profile intentionally leaves
minimaldunconfined and grants it theusernspermission. It does not alter the host-wide setting or affect unrelated binaries, but it does expand the permissions available tominimald; the current wording understates that security tradeoff. Ubuntu documents this as an additional permission that reduces the restriction for the profiled application. (discourse.ubuntu.com)Suggested wording
-Installing it neither sandboxes minimald nor weakens the host. +It does not sandbox minimald or change the host-wide setting; it grants only minimald a named profile with the userns permission.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/reference/linux-host-setup.md` around lines 64 - 72, Revise the AppArmor profile explanation in the section describing `flags=(unconfined)` to remove the claim that installing it does not weaken the host. State that the profile leaves `minimald` unconfined and grants it `userns`, expanding permissions for that application while not changing host-wide settings or affecting unrelated binaries.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/reference/linux-host-setup.md`:
- Around line 105-111: Update the “User namespaces disabled entirely” section to
include kernel.unprivileged_userns_clone as an additional check and remediation,
covering hosts where it is set to 0 alongside CONFIG_USER_NS and
user.max_user_namespaces. If the troubleshooting guidance cannot support this
case, explicitly narrow the section’s scope to the two existing failure modes.
In `@docs/reference/loadouts.md`:
- Around line 24-26: Add an explicit language identifier to both fenced code
blocks in the loadouts documentation: use text for the path example and text or
console for the loadout-list output. Keep the existing fenced content unchanged.
In `@docs/reference/minimal-dot-toml.md`:
- Line 75: Update the sideload documentation example and heading to use
[[upstream.sideloads]] as the primary syntax, and identify [[upstream.sideload]]
only as the accepted compatibility alias.
- Line 3: Update the front-matter description for the minimal.toml reference so
it reflects all documented schema sections, including session, params, cache,
and stdlib, while retaining the existing sections or replacing the list with
accurate broader wording.
- Around line 96-101: Update the primary stack example to use the canonical
`name = "<stack name>"` key instead of `use`. Retain `use` only in the
surrounding documentation as a deprecated compatibility alias, consistent with
the `[stack]` guidance.
---
Outside diff comments:
In `@docs/reference/linux-host-setup.md`:
- Around line 64-72: Revise the AppArmor profile explanation in the section
describing `flags=(unconfined)` to remove the claim that installing it does not
weaken the host. State that the profile leaves `minimald` unconfined and grants
it `userns`, expanding permissions for that application while not changing
host-wide settings or affecting unrelated binaries.
In `@docs/reference/minimal-dot-toml.md`:
- Around line 212-214: Update the raw-file validation rule in the documentation
to explicitly list both vars and its env_vars alias as invalid oci-image-only
fields, while preserving the existing entrypoint, cmd, and path restrictions.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: bbff121e-d4ff-4723-bbec-79d9a8372e16
📒 Files selected for processing (13)
docs/reference/build-specs.mddocs/reference/cli-min.mddocs/reference/cli-minimald.mddocs/reference/cli-minvmd.mddocs/reference/cli-mip.mddocs/reference/cli.mddocs/reference/linux-host-setup.mddocs/reference/loadouts.mddocs/reference/manifest.jsondocs/reference/minimal-dot-toml.mddocs/reference/sandbox-operations.mddocs/reference/stack-specs.mddocs/reference/tasks.md
🚧 Files skipped from review as they are similar to previous changes (9)
- docs/reference/manifest.json
- docs/reference/cli-min.md
- docs/reference/build-specs.md
- docs/reference/cli-minvmd.md
- docs/reference/cli.md
- docs/reference/tasks.md
- docs/reference/cli-mip.md
- docs/reference/sandbox-operations.md
- docs/reference/stack-specs.md
| ## User namespaces disabled entirely | ||
|
|
||
| Separately from the AppArmor restriction, a kernel built without | ||
| `CONFIG_USER_NS`, or a host with `user.max_user_namespaces` set to `0`, cannot | ||
| create user namespaces at all. The daemon's preflight reports this as its own | ||
| error. The fix is distribution-specific: raise `user.max_user_namespaces` via | ||
| sysctl, or use a kernel with user namespaces enabled. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Document kernel.unprivileged_userns_clone as an additional gate.
Some Linux distributions also disable unprivileged user namespaces with kernel.unprivileged_userns_clone=0. Hosts with that setting will produce the same failure but are not covered by this troubleshooting section. Add it to the checks/remediation, or explicitly scope the section to the two supported failure modes. (gitlab.com)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/reference/linux-host-setup.md` around lines 105 - 111, Update the “User
namespaces disabled entirely” section to include
kernel.unprivileged_userns_clone as an additional check and remediation,
covering hosts where it is set to 0 alongside CONFIG_USER_NS and
user.max_user_namespaces. If the troubleshooting guidance cannot support this
case, explicitly narrow the section’s scope to the two existing failure modes.
| ``` | ||
| <config>/minimal/loadouts/<name>.toml | ||
| ``` |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Add language identifiers to both fenced blocks.
The path example and loadout-list output fences trigger markdownlint MD040. Mark them as text or console.
Proposed fix
-```
+```text
<config>/minimal/loadouts/<name>.toml>- +text
NAME DESCRIPTION CONTRIBUTES
- dev helix + zellij with my dotfiles 2 pkg / 4 var / 5 patch / 1 hook
extra 1 pkg / 0 var / 0 patch / 0 hook
@@ - default (from
[loadouts].default_loadouts)
Also applies to: 288-294
🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 24-24: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/reference/loadouts.md` around lines 24 - 26, Add an explicit language
identifier to both fenced code blocks in the loadouts documentation: use text
for the path example and text or console for the loadout-list output. Keep the
existing fenced content unchanged.
Source: Linters/SAST tools
| --- | ||
| description: Schema reference for the minimal.toml configuration file — upstream, stack, defaults, tasks, and outputs sections. | ||
| title: minimal.toml | ||
| description: "Schema reference for the minimal.toml configuration file: upstream, stack, defaults, tasks, and outputs sections." |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Keep the front-matter description synchronized with the documented schema.
The page now documents [session], [params], [cache], and [stdlib], but the description lists only upstream, stack, defaults, tasks, and outputs. Update it to include the new sections or use broader wording.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/reference/minimal-dot-toml.md` at line 3, Update the front-matter
description for the minimal.toml reference so it reflects all documented schema
sections, including session, params, cache, and stdlib, while retaining the
existing sections or replacing the list with accurate broader wording.
| are built using the version of packages from your upstream. | ||
|
|
||
| Each sideload entry is loaded in order from the specified repository, and follows the same schema as `[upstream]`: | ||
| Each sideload entry is loaded in order from the specified repository, and follows the same schema as `[upstream]` (the canonical table name is `sideloads`; `sideload` is an accepted alias): |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
Use the canonical sideload table name in the example.
This text says sideloads is canonical while the heading and example use [[upstream.sideload]]. If the singular form is only an accepted alias, show [[upstream.sideloads]] as the primary syntax and label the singular form as compatibility syntax.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/reference/minimal-dot-toml.md` at line 75, Update the sideload
documentation example and heading to use [[upstream.sideloads]] as the primary
syntax, and identify [[upstream.sideload]] only as the accepted compatibility
alias.
| The `[stack]` section configures the [stack](https://docs.minimal.dev/concepts/stacks) to use for building code, if any. | ||
| See [stack specs](./stack-specs.md) for how stacks themselves are defined. | ||
|
|
||
| `[harness]` is accepted as a deprecated alias for `[stack]`, pending removal after | ||
| `use` is an accepted alias for the canonical `name` key; both parse. `[harness]` | ||
| is accepted as a deprecated alias for `[stack]`, pending removal after | ||
| July 2026; prefer `[stack]` in new configs. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
Use the canonical name key in the primary stack example.
The prose identifies name as canonical but the example above still uses use. Change the example to name = "<stack name>" and document use only as the deprecated/compatibility alias.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/reference/minimal-dot-toml.md` around lines 96 - 101, Update the primary
stack example to use the canonical `name = "<stack name>"` key instead of `use`.
Retain `use` only in the surrounding documentation as a deprecated compatibility
alias, consistent with the `[stack]` guidance.
Fifth PR in the
oss/integrationdecomposition — the CLI & config reference section (WS8, first half). Pure docs. 12 files, +779/−207.What
cli-min.md,cli-mip.md,cli-minimald.md,cli-minvmd.md, plus thecli.mdoverview.minimal-dot-toml.md,tasks.md,build-specs.md,sandbox-operations.md, and theharness-specs.md→stack-specs.mdrename.manifest.json— the reference-page index.Accuracy fix
Removed a stale "known issues" note in the mip reference that cited
dump --stacks(todo!()) andpatched-build --remote-addr. Both were since fixed (dump --stacks by #842) and their issues closed, so citing them as current known issues was inaccurate.Verification
.md/.jsonlink resolves; no danglers. Nothing in this set links toloadouts.md, so deferring it is clean.cli.mdrewrite already omits the--hostpath-depsrow that fix(mip): dump --stacks; remove the dead HostPath build dep variant #842 removed (no reversion);harness-specshas no lingering references.Depends on nothing already merged; branches off current
main. The loadouts page (367 lines) follows as PR6.🤖 Generated with Claude Code
Note
Add CLI command reference pages and update config/spec docs for mip, min, minimald, and minvmd
min) from the package/build plane (mip) and links to new dedicated reference pages for each binary.cli-mip.md,cli-min.md,cli-minimald.md, andcli-minvmd.md, each generated from--helpoutput.minimal-dot-toml.md,build-specs.md,tasks.md, andsandbox-operations.mdto replaceminimal/harnessCLI references withmip/stackterminology and relative links.harness-specs.mdtostack-specs.mdand updates all terminology, file paths, and schema references from harnesses to stacks.manifest.jsonenumerating reference pages for site navigation.Changes since #863 opened
minis the primary session CLI that communicates withminimald, which runs inside a microVM managed byminvmdon macOS and optionally on Linux, and positionedmipas an advanced Linux-only interface to the underlying declarative package and build engine [31995e8]--gvproxy-binflag description for theruncommand in theminimaldCLI reference to indicate it is used for networking and defaults to a typical system install path [31995e8]addoperation documentation in sandbox operations to indicate packages are recorded as session, runtime, or build dependencies inminimal.tomlbased on flags, removed the--taskflag, and updated the--sessionflag description to state it also adds packages to the[session]packages list [31995e8]--minvmdwith--provider <PROVIDER>and added--no-inputflag across CLI reference documentation [d8f700d][session],[params],[cache], and[stdlib]configuration sections inminimal.tomlreference [d8f700d]min attachcommand to make SESSION parameter optional with automatic session resolution and interactive picker behavior [d8f700d]echoaction for tasks that prints a fixed string without composing a sandbox [d8f700d]min addcommand behavior differences between sessions and task sandboxes [d8f700d]mincommand behavior and auto-start exceptions in CLI reference [d8f700d]typefield optional with defaultoci-imagein outputs configuration [d8f700d]~/prefix for tilde expansion in task specifications [d8f700d]run --timeoutand--detachflags from minvmd CLI reference [d8f700d]--stdlib-dirflag is accepted but ignored in minimald CLI reference [d8f700d]Macroscope summarized bfaddc4.
Summary by CodeRabbit
minsession CLI,mip,minimald, andminvmd, plus a newloadoutsguide.minimal.toml.