Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 9 additions & 7 deletions docs/reference/build-specs.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
---
description: Build spec schema for defining Minimal packages in Nickel — build_deps, runtime_deps, commands, outputs, tests, and metadata.
title: Build specs
description: "Build spec schema for defining Minimal packages in Nickel: build_deps, runtime_deps, commands, outputs, tests, and metadata."
---

# Build specs

Build specs declare everything about a [package](/concepts/packages), the fundamental unit of software
Build specs declare everything about a [package](https://docs.minimal.dev/concepts/packages), the fundamental unit of software
in Minimal.

This declaration includes:
Expand All @@ -15,8 +16,8 @@ This declaration includes:
directories used at runtime for state, and a number of other data points.

Build specs are defined in a [Nickel](https://nickel-lang.org/) file located at `packages/<package name>/build.ncl`, either in your codebase
or any layer in your [software supply chain](/concepts/software-supply-chain). The `packages/` directory in a layer is always adjacent to
the [`minimal.toml`](/reference/minimal-dot-toml) file at its base. The directory can be omitted if the layer does not define any packages.
or any layer in your [software supply chain](https://docs.minimal.dev/concepts/software-supply-chain). The `packages/` directory in a layer is always adjacent to
the [`minimal.toml`](./minimal-dot-toml.md) file at its base. The directory can be omitted if the layer does not define any packages.

## Example

Expand Down Expand Up @@ -67,8 +68,9 @@ More examples are maintained in the [Minimal Public Package Registry](https://gi
## Schema

The canonical typing of a Build-spec is defined using [Nickel](https://nickel-lang.org/) in Minimal's
embedded standard library, located
[here](https://github.com/gominimal/minimal/blob/main/crates/stdlib/minimal-ncl/minimal.ncl#L10).
embedded standard library, in
[`crates/stdlib/minimal-ncl/minimal.ncl`](https://github.com/gominimal/minimal/blob/main/crates/stdlib/minimal-ncl/minimal.ncl)
(the `BuildSpec` contract).

| **Field name** | **Type** | **Usage** |
|---|---|---|
Expand All @@ -80,6 +82,6 @@ embedded standard library, located
| `outputs` | Map&lt;String, Output> | The named set of output files that are captured from a build. If no files match a named output, it's a build error. |
| `attrs` | Attrs | The typed set of metadata attached to a given package. |
| `needs` | Needs | Any abstract needs declared on a given package. |
| `tests` | Map&lt;String, Test> | A list of tests that are run by `minimal check`. |
| `tests` | Map&lt;String, Test> | A list of tests that are run by [`mip check`](./cli-mip.md#check). |
| `target` | String | The target string this package supports. Defaults to the current target. |
| `prebuilt` | Bool | Indicates that a package is not built, but just the unpacked files from the first `Source` object in `build_deps`. |
201 changes: 201 additions & 0 deletions docs/reference/cli-min.md
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`

```
Comment thread
norrietaylor marked this conversation as resolved.
Resolved
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.
Comment thread
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
Comment thread
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).
53 changes: 53 additions & 0 deletions docs/reference/cli-minimald.md
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`

```
Comment thread
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.
Loading