mix-shell
mix-shell is the library behind the mix executable: the interactive shell,
script runner, command dispatcher, linter, and supervised Bus citizen host for
Mix programs. The executable itself is built by cli/system, the system
binary, which runs the shell when started as mix.
In the bus <- mix <- cos dependency chain it occupies the Mix layer: it
depends on Bus protocol, client, logging, build-information, and property
crates, and on the mixos-lib-mix language runtime, but it does not depend on
the Cos daemon layer.
Synopsis
mix
mix script.mix [args...]
mix -c 'CODE' [args...]
mix -i -c 'CODE' [args...]
mix - [args...]
mix --check script.mix
mix lint [OPTIONS] FILE...
mix --serve script.mix [--name SERVICE] [--no-prelude]
The Cargo package produces one binary named mix. It does not expose a Rust
library target. References to mixos_mix in its source name the
mixos-lib-mix dependency, not this package.
See Command-line interface for modes, options, subcommands, files, and environment variables. See Serve mode for the supervised Bus runtime and its reserved verbs.
What it provides
- An interactive readline shell with history, completion, aliases, job control, directory stacks, and a Mix-or-shell input classifier.
- A
.mixscript runner with positional arguments, traceback rendering, strict-arity selection, interrupt handling, and an optional standard prelude. - A
-cmode that applies the same classifier as the REPL, so the input may be Mix source or an external command line. - Shell execution for pipelines, redirections, environment prefixes,
expansions, command substitution, background jobs, and
&&,||, and;command lists. - Reference and introspection commands for help, manuals, builtins, keywords, operators, runtime state, and Bus services.
mix lint, a semantic-analysis CLI with human, JSON, and strict-data output.- Usage statistics stored under the XDG state directory, with JSON rotation and optional SQLite queries.
- Bus adapters for transient scripts and supervised
--servecitizens. - Runtime-owned
HELP,INFO,QUIT, and L1 property verbs for every served citizen.
Execution modes
| Mode | Entry point | Behaviour |
|---|---|---|
| Interactive | mix | Starts the REPL, loads the prelude and ~/.mixrc, and maintains history and jobs. |
| Script | mix FILE | Parses and executes a file, then runs its event pump when handlers are registered. |
| Command | mix -c CODE | Classifies and runs Mix code, a Mix function command, or an external command line. |
| Configured command | mix -i -c CODE | Loads ~/.mixrc before classification and execution. |
| Standard input | mix - | Reads Mix source from standard input; bare piped input does not execute implicitly. |
| Check | mix --check FILE | Lexes and parses without evaluating. |
| Lint | mix lint ... | Lexes, parses, and performs semantic analysis. |
| Serve | mix --serve FILE | Registers a named citizen and runs a permanent supervised Bus event pump. |
The REPL, -c, file, and serve evaluators use a recursion limit of 128. Time
and collection limits remain unset. The process runs evaluation on a dedicated
64 MiB stack.
Module map
| Module | Responsibility |
|---|---|
main | Process entry, option parsing, script execution, syntax checking, and serve lifecycle. |
bus | Transient and supervised implementations of the language runtime's BusHandler. |
completion | Readline completion for variables, aliases, Mix words, subcommands, and commands on PATH. |
mixos_paths | Cached resolution of source, configuration, and binary directories. |
exec | Shell tokenisation, expansion, pipelines, redirection, command lists, process launch, and cd. |
jobs | REPL background-job tracking and foreground selection. |
lint | mix lint argument parsing, report formatting, and analyser invocation. |
meta | Help, manuals, introspection, build, diagnostics, mesh, AI, and orchestration commands. |
node_config | Read-only broker URL resolution from node.conf.mix. |
repl | Interactive loop, history, prompt, tracing, directory stack, jobs, and .mixrc loading. |
serve_runtime | Reserved Bus verbs and the lifecycle property tree for served citizens. |
shell | REPL and -c classification between Mix, functions, builtins, and external commands. |
shell_handler | Per-line shell fallback for files loaded through source. |
stats_io | XDG state paths, the append-only JSONL statistics store, its cache and ops, and stats reports. |
These modules are private implementation modules of the binary.
Bus integration
Normal REPL and script execution use MixAmpHandler. It checks a local port
socket first for simple target names, then lazily probes the configured broker.
The handler supports request/reply calls, fire-and-forget emits, port checks,
incoming events, registration, topic subscription, replies, and an explicit
reconnect.
The first failed broker probe marks the process as a host on which the broker
was never present. Calls then report Bus unavailable without repeatedly
probing, emits remain no-ops, and port checks return false. A connection that
was established and later fails is reported as a mesh error. Calling
bus_reconnect() resets the transient handler for a fresh probe.
Serve mode uses MixServeHandler instead. It keeps one supervised broker
connection and registered identity, reconnects after transient broker loss,
and replays its topic subscriptions. It does not use the local-socket shortcut.
Cargo surface
The package declares no Cargo features. It ships one binary flavour with Bus client and citizen support always enabled.
The mixos-lib-mix dependency enables its JSON, regular-expression, TOML,
date/time, URL, cryptography, HTTP, SQLite, Tokio sleep, DKIM, serde, Markdown,
Datastar, and XML capabilities. Other direct dependencies provide:
| Group | Crates |
|---|---|
| Bus | mixos-lib-bus, mixos-lib-client, mixos-lib-buildinfo, mixos-lib-props-core, mixos-lib-log |
| Interactive shell | rustyline, dirs, libc |
| Async runtime | tokio, tokio-util |
| Data and utilities | serde, serde_json, glob, indexmap, chrono, ureq, tracing |
| Tests | proptest |
mixos-lib-props-core is built with its bus feature and without default
features. mixos-lib-client is built with its native feature.
Build information
The build script emits the repository revision, dirty state, and build time.
Serve mode supplies that provenance when it registers the citizen. INFO
reports the mix package version because a served script has no separate
binary version.
Limits
- The package has no embeddable library API; use
mixos-lib-mixto embed the language. - The local node configuration reader is deliberately narrow and read-only.
- Serve mode provides property conformance through L1. It does not provide runtime-owned property watch, mutation, or world aggregation.
- Serve-mode log filtering is configured through
RUST_LOGand a restart; the package does not include the Cos-side mutable property store.