Repository navigation
docs(reference): add CLI command reference and config/spec pages #863
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
6 commits
Select commit
Hold shift + click to select a range
d6e7d25
docs(reference): add CLI command reference and config/spec pages
norrietaylor 57dd6d1
docs(reference): drop phantom mip dep flag, add min activate --no-pro…
norrietaylor bfaddc4
docs(reference): scope down min CLI surface and fix reference inaccur…
norrietaylor 31995e8
docs(reference): address review feedback on mip and in-sandbox add
norrietaylor d8f700d
docs(reference): align CLI and config reference with the current binary
norrietaylor 0c6204d
docs(reference): add the loadouts reference page (#868)
norrietaylor File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,201 @@ | ||
| --- | ||
| title: min CLI | ||
| description: "Reference for the min session CLI: create, attach to, and manage sandboxed development sessions, plus the git-remote-min helper." | ||
| --- | ||
|
|
||
| # `min` - session CLI | ||
|
|
||
| `min` is the Minimal session CLI. It talks to the `minimald` daemon (see | ||
| [minimald](./cli-minimald.md)) to create, attach to, and manage sandboxed | ||
| development sessions. Most commands start the daemon automatically when it | ||
| isn't running (`bug`, `stop`, and `version` are the exceptions): natively on | ||
| Linux, or inside the [`minvmd`](./cli-minvmd.md) microVM host daemon on macOS | ||
| (and on Linux under `--provider local-minvmd`). Running bare `min` with no | ||
| subcommand resolves a session for the current directory (activating one if | ||
| needed) and attaches to it. | ||
|
|
||
| Generated from `--help` at `3a05252c`. | ||
|
|
||
| ## Global flags | ||
|
|
||
| These apply to every subcommand. | ||
|
|
||
| | Flag | Short | Description | | ||
| |------|-------|-------------| | ||
| | `--repo-dir <PATH>` | `-C` | Use the given directory as the repository root, instead of the current working directory | | ||
| | `--minimal-dir <PATH>` | | Override the base directory used for operations (default: `~/.cache/minimal`) | | ||
| | `--config-dir <PATH>` | | Override the user config directory; everything under `<config_dir>/minimal/` (`config.toml`, `loadouts/`, ...) resolves relative to it. Defaults to `$XDG_CONFIG_HOME` on Linux (or `$HOME/.config`); macOS also uses `$HOME/.config` | | ||
| | `--provider <PROVIDER>` | | Daemon backend that hosts sessions: `local-minimald` (Linux default, `minimald` natively on the host) or `local-minvmd` (`minimald` inside the `minvmd` microVM). No effect on macOS, where `minvmd` is the only backend | | ||
| | `--no-input` | | Skip interactive prompts that need a terminal (such as the session picker); ambiguous choices error with a list of candidates instead. Implied when stdin/stdout is not a terminal | | ||
|
|
||
| ## Commands | ||
|
|
||
| ### `ls` | ||
|
|
||
| ``` | ||
| min ls [--raw] [--json] | ||
| ``` | ||
|
|
||
| Lists sessions. `--raw` prints raw session IDs one per line for piping | ||
| into scripts; `--json` prints the full session list as pretty-printed | ||
| JSON. When the daemon reports a shared resource pool, the table is headed | ||
| by a `RESOURCE POOL:` line (CPU cores, memory, and the number of sessions | ||
| sharing them); `--raw` omits it. | ||
|
|
||
| ### `activate` | ||
|
|
||
| ``` | ||
| min activate [OPTIONS] [PATH] | ||
| ``` | ||
|
|
||
| Activates (creates) a new session for the project at `PATH` (defaults to | ||
| the current directory). | ||
|
|
||
| | Flag | Short | Description | | ||
| |------|-------|-------------| | ||
| | `--name <NAME>` | `-n` | Optional session name | | ||
| | `--sync <MODE>` | | How to load project files into the session: `tarball` (default: stream a tarball of your project and unpack it) or `none` (do not populate the worktree) | | ||
| | `--network <MODE>` | | Network mode: `no-net`, `host-net` (default), or `own-ip` | | ||
| | `--ingress <EXT:INT[/PROTO]>` | | Static ingress port mapping (`PROTO` = `tcp`\|`udp`, default `tcp`). Repeatable. Requires `--network own-ip` | | ||
| | `--loadout <NAME>` | | Apply the named loadout from `<config>/minimal/loadouts/<NAME>.toml`. Repeatable; if given, config-file `default_loadouts` are ignored | | ||
| | `--no-loadouts` | | Apply no loadouts at all (also skips the config's `default_loadouts`). Conflicts with `--loadout` | | ||
| | `--no-prompt` | | Fail instead of prompting when the daemon surfaces items user policy can't auto-decide; implied when stdin/stderr isn't a TTY | | ||
| | `--attach` | | Automatically attach after creation | | ||
|
|
||
| ### `attach` | ||
|
|
||
| ``` | ||
| min attach [-c <COMMAND>] [SESSION] | ||
| ``` | ||
|
|
||
| Attaches to an existing session, identified by UUID or session name. When | ||
| `SESSION` is omitted, `min attach` resolves a session from the current | ||
| working directory (or the only existing session) and opens an interactive | ||
| picker if the choice is ambiguous (`--no-input` errors instead). | ||
| `-c/--command` execs a command in the session context non-interactively | ||
| instead of opening an interactive shell; the daemon accepts only | ||
| `min run <task name>` invocations on this channel, not arbitrary commands. | ||
|
|
||
| ### `destroy` | ||
|
|
||
| ``` | ||
| min destroy [--all] [-f|--force] [SESSION] | ||
| ``` | ||
|
|
||
| Destroys (terminates) a session. `--all` destroys all sessions; | ||
| `-f/--force` skips the confirmation when destroying all sessions. | ||
|
|
||
| ### `stop` | ||
|
|
||
| ``` | ||
| min stop [-f|--force] | ||
| ``` | ||
|
|
||
| Shuts down the `minimald` daemon. `--force` shuts down even if active | ||
| sessions exist. | ||
|
norrietaylor marked this conversation as resolved.
Resolved
|
||
|
|
||
| ### `loadout list` (alias: `ls`) | ||
|
|
||
| ``` | ||
| min loadout list [--dir <DIR>] | ||
| ``` | ||
|
|
||
| Lists loadouts from the user's config directory. `--dir` overrides the | ||
| loadouts directory (default: `<config>/minimal/loadouts`, e.g. | ||
| `~/.config/minimal/loadouts` on Linux). | ||
|
|
||
| ### `dirs` | ||
|
|
||
| ``` | ||
| min dirs | ||
| ``` | ||
|
|
||
| Prints important directories and file paths for debugging. | ||
|
|
||
| ### `bug` | ||
|
|
||
| ``` | ||
| min bug [-o <OUTPUT>] | ||
| ``` | ||
|
|
||
| Collects a diagnostic bundle (logs, state, config) to send to the minimal | ||
| dev team. Writes `minimal-diag-<timestamp>.tar.zst` to the current | ||
| directory; `-o/--output` overrides the path. The archive contains host | ||
| system facts, log tails, redacted config, and state listings, plus a | ||
| `manifest.json` recording any collector that failed or timed out; a | ||
| broken install still yields a valid archive that explains what is | ||
| missing. | ||
|
|
||
| Diagnosing a wedged system must not change it: `bug` mutates no state and | ||
| never starts a daemon; it works even when none is running. | ||
|
|
||
| Secret-shaped values (env vars, tokens) are redacted before they enter | ||
| the archive: only a small allowlist of env names (`RUST_LOG`, `HOME`, | ||
| `SHELL`, `TERM`, `PATH`, and the `XDG_*` / `MINIMAL_*` / `MINVMD_*` / | ||
| `MINIMALD_*` prefixes) has values captured verbatim (a sensitive-shaped | ||
| name always loses to the allowlist), and every other env var is reported | ||
| by name only. Session and project file contents are never included, only | ||
|
norrietaylor marked this conversation as resolved.
Resolved
|
||
| name/size listings. Review the archive before sharing. | ||
|
|
||
| ### `rename` | ||
|
|
||
| ``` | ||
| min rename <SESSION> <NEW_NAME> | ||
| ``` | ||
|
|
||
| Renames an existing session. | ||
|
|
||
| ### `init`, `add`, `update` | ||
|
|
||
| ``` | ||
| min init [-y|--yes] | ||
| min add <--runtime|--build|--task <TASK>> <PACKAGES>... | ||
| min update | ||
| ``` | ||
|
|
||
| Project-configuration conveniences mirroring the corresponding `mip` | ||
| commands: initialize minimal configuration from your source tree, add a | ||
| tool or dependency, and refresh local checkouts of upstream packages and | ||
| the standard library. See the [mip reference](./cli-mip.md) for details. | ||
|
|
||
| ### `version` | ||
|
|
||
| ``` | ||
| min version | ||
| ``` | ||
|
|
||
| Prints CLI and daemon version information. | ||
|
|
||
| ### `completions` | ||
|
|
||
| ``` | ||
| min completions <SHELL> | ||
| ``` | ||
|
|
||
| Generates a shell tab-completion script. Supported shells include `bash`, `zsh`, | ||
| `elvish`, `fish`. Usage: `source <(min completions bash)`. | ||
|
|
||
| ## `git push min://` - the git remote helper | ||
|
|
||
| Installs of `min` lay down a `bin/git-remote-min` symlink pointing at the | ||
| `min` binary. The binary dispatches on `argv[0]`: when invoked with the | ||
| basename `git-remote-min` (which is how git invokes remote helpers for | ||
| `min://` URLs), it speaks the | ||
| [gitremote-helpers](https://git-scm.com/docs/gitremote-helpers) line | ||
| protocol on stdio instead of the normal CLI. | ||
|
|
||
| This lets you add a session's workspace as a git remote and push to or | ||
| fetch from it directly: | ||
|
|
||
| ``` | ||
| git remote add session min://<session> | ||
| git push session | ||
| ``` | ||
|
|
||
| Only the `connect` capability is implemented: on `connect`, the helper | ||
| opens an exec channel to `minimald` over its Unix domain socket (the same | ||
| transport the rest of the CLI uses) and bridges git's pack-protocol | ||
| conversation across it; no external `ssh` or `socat` involved. Only the | ||
| two pack services (`git-upload-pack`, `git-receive-pack`) are accepted. | ||
| If the daemon is not running, the helper starts it, using default global | ||
| flags (git invokes helpers without any of `min`'s own flags). | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,53 @@ | ||
| --- | ||
| title: minimald daemon | ||
| description: "Ops reference for the minimald host daemon: serves sandboxed sessions to the min CLI over SSH-on-UDS." | ||
| --- | ||
|
|
||
| # `minimald` - host daemon | ||
|
|
||
| `minimald` is the Minimal host daemon. It creates and supervises the | ||
| sandboxed sessions that the [min CLI](./cli-min.md) connects to, speaking | ||
| SSH over a Unix domain socket (or vsock when hosted inside the `minvmd` | ||
| microVM). End users normally never run it by hand: `min` auto-starts a | ||
| native daemon on Linux, and [minvmd](./cli-minvmd.md) supervises it | ||
| inside the microVM. | ||
|
|
||
| Generated from `--help` at `3a05252c`. | ||
|
|
||
| ## Global flags | ||
|
|
||
| | Flag | Short | Description | | ||
| |------|-------|-------------| | ||
| | `--minimal-state-dir <PATH>` | | Override the directory where state is stored (default: `$XDG_STATE_HOME/minimal`) | | ||
| | `--minimal-cache-dir <PATH>` | | Override the directory where artifacts are cached (default: `$XDG_CACHE_HOME/minimal`) | | ||
|
|
||
| ## Commands | ||
|
|
||
| ### `run` | ||
|
|
||
| ``` | ||
|
norrietaylor marked this conversation as resolved.
Resolved
|
||
| minimald run [OPTIONS] | ||
| ``` | ||
|
|
||
| Runs the minimald server in the foreground. | ||
|
|
||
| | Flag | Description | | ||
| |------|-------------| | ||
| | `--instance-num <N>` | Instance number for this minimald; determines client-relevant paths under `<minimal_state_dir>/providers/local-minimald<N>`. The SSH socket is accessible as `ssh.sock`. Default: `0` | | ||
| | `--vsock` | Host the SSH socket over vsock instead of UDS; the vsock port is the default port base plus `instance_num` | | ||
| | `--detach` | Daemonize: spawn minimald in a new session (setsid) and return once the SSH socket accepts connections, or an 8s timeout elapses. Used by the `min` CLI to auto-start a native daemon on Linux | | ||
| | `--gvproxy-bin <PATH>` | Path to the gvproxy ("gvisor-tap-vsock") binary used for networking. Defaults to a typical system install path. | | ||
|
|
||
| ### `completions` | ||
|
|
||
| ``` | ||
| minimald completions <SHELL> | ||
| ``` | ||
|
|
||
| Generates a shell tab-completion script for `minimald`. Supported shells include | ||
| `bash`, `zsh`, `elvish`, `fish`. Usage: | ||
| `source <(minimald completions bash)`. | ||
|
|
||
| ## Known issues | ||
|
|
||
| - `minimald` accepts but ignores the hidden `--stdlib-dir` flag. | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.