Rune command and runtime reference

Requirements and platform matrix

This matrix describes source-declared archive targets, not a claim that a particular archive is currently published. Check the actual release assets and matching release notes. The candidate's Linux ABI floor is glibc 2.31.

The installer uses a POSIX shell, curl, tar, install, and either sha256sum or shasum. A writable binary directory and private writable home are required. Git authoring commands use Git. No universal macOS minimum version or support for every Linux distribution is established by this page. Flint adds Linux kernel and operator prerequisites.

CLI syntax

rune --help and each subcommand's --help are the installed build's syntax reference. Global --home ROOT selects an absolute Rune root. Precedence is the explicit option, then RUNE_HOME, then $HOME/.rune. Global --json requests one JSON envelope on stdout.

rune init NAME

Provisions a named home. It does not start a process. Valid names match [a-z0-9][a-z0-9-]{0,62}.

rune start NAME

Runs a named foreground process and serves managed Git SSH. SIGINT and SIGTERM shut it down gracefully.

rune status NAME

Reads live process, deployment, persistence, and endpoint status.

rune service generate NAME --system SYSTEM [--output PATH]

Generates systemd, launchd, or openrc definitions. It does not install or enable them.

rune git url NAME

Reports the managed SSH Git URL. Live endpoint discovery requires a serving process.

rune git clone NAME [DESTINATION]

Clones using the Rune-owned writer key and pinned managed-host entry. Requires start.

rune skills [NAME]

Prints the bundled skill without a name, or a named home's skill path and guidance.

rune exe NAME COMMAND [ARGS]...

Runs a declared defcli command in the active immutable deployment.

rune exe --repo PATH COMMAND [ARGS]...

Runs the selected working tree. Artifacts and disk SQLite belong to its .rune/ directory.

rune steel fmt [--check] --repo PATH

Formats Scheme, or reports dirty files without writing.

rune steel check --repo PATH

Loads modules/main.scm. It is not a type checker.

rune steel test --repo PATH

Runs tests/*_test.scm and reports failing files and assertions.

rune steel repl --repo PATH

Starts interactive Steel with repo access and host primitives.

rune forge ..., rune init --import CAPSULE DESTINATION

Linux maintainer-only capsule preview. See Forge prerequisites and unsupported targets. Explicit --home conflicts with import.

No stop, restart, direct specialization, production MCP process, or general capsule run subcommand is part of this CLI contract.

Runtime configuration

The named home's runtime.toml is separate from its immutable program bundle. Config structures reject unknown fields. File changes take effect on process restart. Do not copy credentials or an operator's identity settings into a source checkout.

[network.service_http]

max_body_bytes defaults to 8192. handler_workers defaults to 1. Both must be greater than zero.

[network.service_http.endpoint]

kind = "disabled" is the provisioned default. kind = "tcp" requires a loopback address. kind = "unix" requires an absolute, lexically canonical, non-symlink path below the named home's run/.

[network.ssh]

Contains enabled, bind, idle_timeout_secs, and max_sessions. Provisioning supplies managed identities and a local endpoint. Enabled SSH requires an owner key or SSH identity.

[security]

Contains owner key paths, SSH identities, host-key path, and password-auth configuration. Generated managed keys are private operational state.

[tracing]

log_level defaults to info.

Supported overrides include RUNE_NETWORK_SSH_ENABLED, RUNE_NETWORK_SSH_BIND, RUNE_NETWORK_SERVICE_HTTP_MAX_BODY_BYTES, RUNE_NETWORK_SERVICE_HTTP_HANDLER_WORKERS, RUNE_SECURITY_OWNER_KEYS, and RUNE_LOG_LEVEL. An endpoint choice still belongs to the validated config. Removed model, loop-budget, telemetry, and A2A configuration is not supported.

Scheme, commands, and capability contracts

The runtime profile is rune-sdk-v1. Sibling .scm requires stay inside the repo. Allowed built-in modules include steel/result, steel/option, steel/async, steel/sync, and steel/iterators. Steel cogs and steel/json requires are not supplied by Rune. The generated stdlib reference is authoritative for primitives.

The bundled skill permits top-level define-syntax with syntax-rules outside defmodule. Macros inside defmodule, syntax-case, and defmacro are outside that policy. Prefix internal helper names because definitions inside modules can collide without a check failure. No new authoring capability is promised by this guide.

A defcli command declares name, handler, summary, optional capabilities, and typed option forms. Option types are string, integer, boolean, path, and an explicit string enum. Handler requests include typed args, repo_root, cwd, and artifact_root. Named execution materializes the active bundle privately. Repo execution uses the canonical checkout. Both preserve the caller's working directory.

Relative path values resolve beneath repo_root. Named execution rejects absolute or parent-escaping path options with invalid_path before calling Scheme. Capabilities such as repo:read and artifacts:write describe access. Declaring a command does not grant arbitrary host execution.

Process execution is closed by default. RUNE_PROCESS_POLICY_JSON maps selectors to canonical executable, working_directory, and optional fixed environment. process/spawn accepts those selectors. Poll, wait, and kill have bounded process-group cleanup behavior. Native sandbox, credential, HTTPS, and content-store operations require separate operator authority.

Results and errors

The global CLI JSON success shape is {"ok":true,"command":"...","data":...}. A failure contains ok:false, command, and error with code, message, and retryable. It may include diagnostic data. Failed commands return a nonzero exit status.

The defcli handler contract is different. Its JSON includes ok, summary, artifacts, missing, warnings, and next_safe_step. Missing items are objects with field and impact. Extra handler fields are dropped from exe output. Artifact entries with content are written under the invocation's artifact root. Read the artifact for application-specific details.

Host primitives return structured results whose shape varies by operation. json/object-get commonly returns encoded JSON tokens. The token "true" is not Scheme #t. Use the documented conversion, such as json/string-value, before comparing. File, process, and socket operations return a handle field. Extract it before read, wait, or close calls.

SQLite open uses the logical name as its handle. query returns result.rows. query-one returns result.row. begin returns an opaque transaction token in result. SQLite cells and parameters encode null, signed 64-bit integers, finite reals, UTF-8 text, or base64 blobs.

Common error codes include invalid_name, invalid_home, rune_not_initialized, invalid_path, storage_unavailable, and command_failed. Read the code and message at the layer that failed. A CLI envelope's success does not establish that every nested application outcome succeeded.

Generated references

rune steel docs generate --repo PATH writes docs/program-reference.md and docs/program-index.json from program ;;! comments. It also writes docs/stdlib-reference.md and docs/stdlib-index.json for the runtime profile. These files provide symbol signatures, examples, errors, and capability details.

rune steel docs show --repo PATH shows the program reference. rune steel docs stdlib --repo PATH shows the stdlib reference. Use these files from the matched build for complete lookup rather than assuming an API result is a primitive value.

HTTP and MCP limits

HTTP routes are exact method and path declarations. Methods are case-sensitive valid HTTP tokens. Unregistered routes return 404. Rune does not invent successful health or readiness routes. The body limit defaults to 8192 bytes.

One handler worker preserves its Scheme globals across requests. Above one worker, each worker has separate globals and connection registries, but shares the durable SQLite files. Handlers and lifecycle hooks must be idempotent when using multiple workers.

There is no Rune-level cap on declared routes, accepted connections, or pending dispatch count. Pending work waits asynchronously. Native handle safety limits still apply. A higher worker count is not admission control or a hostile-client boundary.

MCP registrations in a program do not establish an available production process entrypoint. This CLI has no production MCP process entrypoint. Do not infer runnable hosting instructions or callable operation paths from registry metadata. Flint's versioned HTTP contract documents this distinction.

Runtime status

Status separates the current process from deployment history. The nested candidate projection includes process.state, process.instance_id, process.readiness, persistence.mode, specialization.state, specialization.commit, specialization.cli_commands, specialization.http, current_deployment, last_deployment, and endpoints. Product identity, runtime identity, and named instance are distinct.

Process states are stopped, starting, and running. A stopped process has no live endpoints. Specialization states include inactive, active, and corrupt. Deployment states include idle, in_progress, completed, and failed. Persistence distinguishes durable and ephemeral.

Older output and bundled guidance can use flat fields such as active_capabilities and last_successful_main. Do not hard-code those fields against a different build. A status file or old successful commit does not prove a live process. Read status with the same root and name as start.