Skip to content

Reference

CLI

Written by a human with AI assistance

The submilli command tree: what each command does and where it runs, exit codes, environment variables, the state directory, Package installation and its errors, the GitHub token, and the help text of every command.

This page describes submilli, the command-line tool. It covers the command tree, the behaviour every command shares, Package installation and the GitHub token it uses, and the help text of every command. The help text closes the page, one section per command from submilli run to submilli server mcp auth-status, generated from the binary’s --help.

submilli has fourteen top-level commands. Local commands run on this machine and need no server. Server commands send HTTP requests to a running submilli-server.

Command Does Runs
run Compile a program and run its main, optionally under a Blueprint Local
check Compile and type-check a program without running it Local
build Scaffold, compile, test, and install the Packages of a project (submilli.toml) Local
install Fetch a Package from GitHub, compile it, and put it in the local store, pinned to a commit Local, fetches from GitHub
docs Print a module’s, Package’s, or built-in’s description and declarations Local
search List standard-library modules and installed Packages matching a substring Local
builtins List the language built-ins, or print the declarations of named ones Local
skill Install, check, and update the coding-assistant skill Local, and sync fetches releases
upgrade Replace submilli and submilli-server with a published release Local, fetches releases
blueprint Create and edit a local blueprint.yaml Local
secret Manage the local secret store Local
mcp Authenticate a Blueprint’s OAuth MCP servers into the local secret store Local, contacts the MCP server’s OAuth host
github Manage the GitHub token that install and build send Local, contacts GitHub
server Run code, manage Blueprints, Packages, secrets, sessions, and MCP credentials on a server Server

Several local commands have a submilli server counterpart that does the same job against a server’s state. A server has its own Blueprints, Package store, and secret store.

Local Server Difference
submilli run --blueprint <file> submilli server run-code --blueprint <name> or --session <id> The local run reads a Blueprint file, and the server run names a registered Blueprint or an open session
submilli blueprint … submilli server blueprint add, apply, list, show, remove The local commands edit a file, and the server commands register, list, and remove Blueprints
submilli docs <name> --blueprint <file> submilli server docs <name> --blueprint <name> The server reads a registered Blueprint’s catalog
submilli install <repo>[@<ref>] submilli server packages install <repo> [--sha <ref>] The local install sends your GitHub token. The server fetches with its own (github_token_file) and never receives yours
submilli secret put, delete, list submilli server secret put, delete, list The local store is plaintext owner-only files, and the server’s is encrypted
submilli mcp authenticate, deauthenticate, auth-status submilli server mcp authenticate, deauthenticate, auth-status Locally the Blueprint is a file (--blueprint <file>), and on the server it is a registered name (positional)
submilli search submilli server packages list search lists installed Packages and the standard library, and packages list lists the server’s stores

A server on the same machine and with the same SUBMILLI_HOME also reads the local packages/ directory, as a fallback store it never writes.

submilli server secret delete returns HTTP 404 when the secret does not exist, including after it has already been deleted. Local submilli secret delete succeeds when the secret is already absent.

Every submilli server command that sends a request takes two options, --server and --token-file:

Option Environment variable Default
--server <URL> SUBMILLI_SERVER_URL http://127.0.0.1:8128
--token-file <PATH> SUBMILLI_SERVER_TOKEN_FILE none

The token is read from the file when one is named, otherwise from SUBMILLI_SERVER_TOKEN. With neither, no token is sent, which only a server started with --allow-unauthenticated accepts. No option takes the token itself. Surrounding whitespace in the file or variable is dropped. An empty file is an error, and an empty variable counts as unset. A token the server does not accept gives:

error: the server did not accept this command's API token. Set `SUBMILLI_SERVER_TOKEN` to the token the server was started with, or `SUBMILLI_SERVER_TOKEN_FILE` to a file holding one

A token has the role user or admin. run-code, session open and close, and docs accept either. status, stop, apply, and the blueprint, packages, secret, and mcp groups need admin. Connect the CLI shows how to set both up for a shell.

Code Meaning
0 The command succeeded
1 The command failed. This includes a program that failed to compile or threw from run (except a denial, below), a blueprint lint error, server status with no server running, skill status for a missing, outdated, or modified installation, and upgrade --check when a newer release exists
2 The command line was invalid: an unknown command or option, or a missing argument
3 run only: the program let a permission denial escape, a gated call the Blueprint or the runtime refused (an invariant or a read-only volume) that no catch handled. The message is the same text exit code 1 prints

Errors go to standard error. A command’s own errors begin with error:. An error that stopped the command before it could report one begins with Error: and may add a Caused by: section. submilli server stop exits 0 when no server is running, printing already stopped (no server at <URL>).

Variable Read by Effect
SUBMILLI_HOME Every command The state directory (see State directory)
SUBMILLI_SERVER_URL server … The server’s base URL. An empty value means the default
SUBMILLI_SERVER_TOKEN server … The API token, when no token file is named
SUBMILLI_SERVER_TOKEN_FILE server … A file holding the API token. --token-file takes precedence
GH_TOKEN, GITHUB_TOKEN install, build, github … A GitHub token (see GitHub token)
SUBMILLI_MAX_EXECUTION_LLM_TOKENS run Default for --max-llm-tokens
SUBMILLI_MAX_LLM_CONCURRENCY run Default for --max-llm-concurrency
SUBMILLI_MAX_EXECUTION_EMBEDDING_TOKENS run Default for --max-execution-embedding-tokens
SUBMILLI_MAX_EXECUTION_EMBEDDING_REQUESTS run Default for --max-execution-embedding-requests
SUBMILLI_MAX_EMBEDDING_CONCURRENCY run Default for --max-embedding-concurrency
SUBMILLI_OAUTH_REDIRECT_PORT mcp authenticate, server mcp authenticate Loopback port of the OAuth redirect listener, 8765 by default
SUBMILLI_SKILL_AUTOUPDATE skill sync 0 stops sync from contacting the network. It then uses the skill bundled with the CLI
SUBMILLI_SKILL_SOURCE skill sync Repository URL skill releases are downloaded from. Must be https, or http on loopback
SUBMILLI_RELEASE_SOURCE upgrade, skill sync Repository URL CLI releases are downloaded from. Must be https, or http on loopback. Default https://github.com/submilli/submilli-runtime
SUBMILLI_TELEMETRY Every command 1, true, yes, or on sends crash reports and per-command counters (command name and which flags were set, never their values). Off by default

The CLI keeps its state under $SUBMILLI_HOME when it is set and not empty, otherwise under ~/.submilli.

Path Holds Written by
packages/ The local Package store, one directory per Package (packages/@org/name/) install, build publish-local, build for GitHub dependencies
secrets/ The local secret store, one owner-only (0600) plaintext file per key, in an owner-only directory. Holds store: secrets for run --blueprint and MCP OAuth credentials under mcp_oauth/<blueprint>/<server>/credential secret put, mcp authenticate
mcp_oauth.yaml Local OAuth provider apps: client id, client secret reference, and scopes per OAuth host. Owner-only mcp provider add, remove
github_token The stored GitHub token. Owner-only (0600) github authenticate, and removed by github deauthenticate
skill-release.json The cached result of the daily skill-release check skill sync
cli-release.json The cached result of the daily CLI-release check skill sync
server/ A local submilli-server’s own state. The CLI never reads or writes it submilli-server

The secret store is not encrypted. A separate secrets/ and server/ keep the CLI’s plaintext store and a local server’s encrypted store apart.

submilli build works on a project, a directory with a submilli.toml holding one [[package]] block per Package. Every build subcommand except init finds the manifest in the current directory or the nearest parent that has one. Package manifest describes the file.

Subcommand Does
build init [@scope/name] [path] Writes submilli.toml with a first Package at path (default .), and scaffolds src/lib.ts, docs/readme.md, README.md, and tests/lib.test.ts, plus tsconfig.json, .vscode/, .submilli/, and .gitignore. Prompts for the name when it is omitted
build new <@scope/name> <path> Adds a Package to submilli.toml and scaffolds its folders
build check Compiles the Packages in dependency order and writes each one’s capabilities.yaml beside its source. Installs nothing
build test Compiles, then runs tests/**/*.test.{ts,subm} and compile-checks the readme’s examples
build publish-local Compiles, then installs the Packages into the local store

check, test, and publish-local take -p <@scope/name> to compile one Package and the sibling Packages it depends on. Before compiling, they fetch the project’s GitHub dependencies into the local store, with the GitHub token, and record the commits in submilli.lock beside submilli.toml. A lock that already pins every dependency, with the store holding them, skips the fetch. A compile error exits 1.

checked @pied-piper/billing v0.1.0
installed @pied-piper/billing v0.1.0 -> …/packages/@pied-piper/billing

Tests receive no credentials unless build test is given them:

Option Supplies
--env-var <NAME> One process variable. Repeatable, or comma-separated. Fails if unset or not Unicode
--env-file <PATH> NAME=value entries from a file, relative to the current directory. Fails if unreadable
--all-env Every Unicode process variable

When a name is supplied more than once, --env-var wins over --env-file, which wins over --all-env, whatever the argument order. --skip-network skips network.test.{ts,subm} and network_*.test.{ts,subm} anywhere under tests/.

submilli install installs into the local store and submilli server packages install into a server’s store. Both fetch a GitHub repository at one commit, resolve its GitHub dependencies, compile the Packages its submilli.toml declares, and store them pinned to that commit. The repository is org/repo, github.com/org/repo, or a full URL. A second argument, @org/name, installs only that Package. Without it, every Package the repository declares is installed. A Package must be scoped to the repository’s owner. For example, submilli/pied-piper can hold only @submilli/… Packages.

submilli install submilli server packages install
Pin to a branch, tag, or commit org/repo@<ref> --sha <ref>
Configuration --config NAME=VALUE (selected Package only) --config NAME=VALUE (selected Package only)
Clear a saved override --reset-config NAME --reset-config NAME
Configuration contract Package configuration Package configuration
Without a pin The default branch’s head The default branch’s head
GitHub token Yours (see GitHub token) The server’s github_token_file. The CLI sends none
Replace a Package with changed source or configuration --upgrade --upgrade

The first install reports the commit and the Package’s location:

Terminal window
submilli install submilli/pied-piper@v0.1.1 @submilli/pied-piper-billing
fetched github.com/submilli/pied-piper at c18d9a602bbb
installed @submilli/pied-piper-billing v0.1.0 -> …/packages/@submilli/pied-piper-billing

The same command again, with the Package already installed at that commit, changes nothing and exits 0:

fetched github.com/submilli/pied-piper at c18d9a602bbb
up to date @submilli/pied-piper-billing

A Package installed at another commit is refused, exit 1, until --upgrade is given. In this output template, <installed-commit> is the commit already in the store:

fetched github.com/submilli/pied-piper at c18d9a602bbb
error: `@submilli/pied-piper-billing` is already installed from github.com/submilli/pied-piper@<installed-commit>; pass --upgrade to replace it with c18d9a602bbb

On a server the three outcomes are:

installed @submilli/pied-piper-billing @ c18d9a602bbb
up to date @submilli/pied-piper-billing
error: @submilli/pied-piper-billing already installed at a different commit; retry with --upgrade to replace with c18d9a602bbb

submilli install writes only to the store. It changes no Blueprint and no manifest. When it finds no public repository and no token was sent, and both standard input and standard error are a terminal, it offers to store a GitHub token and, if one is stored, tries once more. Install private Packages on a server describes the server’s token and its errors.

submilli install and submilli build send a GitHub token when one is available, which lets them read private repositories. The token comes from the first of these sources that has one:

Order Source
1 GH_TOKEN
2 GITHUB_TOKEN
3 The token stored by submilli github authenticate, in $SUBMILLI_HOME/github_token
4 The GitHub CLI’s token, gh auth token --hostname github.com, when gh is installed, logged in, and answers within 5 seconds

An environment variable that is set but empty is skipped. One that holds something other than a token is skipped with a warning such as warning: ignoring `GH_TOKEN`: …. With no source, fetches are anonymous and reach public repositories only, at GitHub’s lower anonymous rate limit. A token needs Repository permissions → Contents: Read-only on the Package repositories (a fine-grained token) or the repo scope (a classic token).

Command Does
github authenticate [--owner <owner>] Reads a token (at a terminal with echo off and the token-creation link printed, otherwise from standard input), checks it with GitHub, and stores it, replacing any earlier one. --owner fills the owner into the link
github auth-status Prints which source is in use and, after asking GitHub, whose token it is and when it expires. Never prints the token
github deauthenticate Removes the stored token, and says which source fetches still use, if any

authenticate prints ✓ stored a GitHub token for <login> (<expiry>) in <path>, where the expiry is never expires or expires <date>. With no token in any source, auth-status and deauthenticate print:

✓ no GitHub token: packages are fetched from public repositories only; run `submilli github authenticate` to reach private ones
✓ no GitHub token was stored

authenticate adds ; `GH_TOKEN` is set and is used instead until you unset it when an environment variable outranks the stored token.

submilli install, and submilli build when it fetches dependencies, print these errors and exit 1. Messages name the repository, the token’s source (such as the GitHub token in `GH_TOKEN`), and, where a token is missing or wrong, the token-creation link.

Error begins Cause Fix
GitHub has no public repository `org/repo` or no public commit … in No token was sent, and the repository is private, misnamed, or lacks the commit A token that can read the repository, from any source, lets the fetch see it
GitHub has no repository … that <source> can read or no commit … that A token was sent and GitHub showed nothing, because the name is wrong, the token has no Contents access to the repository, or a fine-grained token awaits the organization’s approval Contents: Read-only on the repository, or the organization’s approval, clears it
resolving org/repo ref `<ref>`: GitHub found no such branch, tag, or commit The @<ref> names nothing in the repository A ref the repository has clears it
GitHub refused <source> for GitHub answered 403 to the token because it lacks Contents access, or the organization requires approval or forbids this kind of token or its expiry Contents: Read-only there, or the organization’s approval, clears it
GitHub rejected <source> (expired or revoked) The token is expired or revoked. As a warning, fetches went on without it. As an error, the repository was not public A new token from the same source clears it
`org/repo` is in an organization that uses SAML single sign-on: authorize The token is not authorized for the organization’s single sign-on Authorizing it, at the link in the message or with Configure SSO on the token, clears it
GitHub's rate limit is used up; try again in about N min The rate limit for this token, or for anonymous requests, is exhausted It clears after the time given. A token has a higher limit than anonymous requests
`@org/name` is already installed from github.com/org/repo@<sha>; pass --upgrade The Package is in the store at another commit --upgrade replaces it
package `@org/name` from github.com/org/repo must be scoped `@org/...` The Package’s scope is not the repository’s owner —
package `@org/name` is not declared in submilli.toml The named Package is not in the repository’s manifest. The message lists the declared ones —
… has no submilli.toml at its root The repository is not a Submilli Package repository —

submilli github authenticate adds three more errors:

Error begins Cause
the GitHub token is empty Nothing was entered or piped
that is not a GitHub token: expected one line of visible ASCII The input is not a single token
GitHub won't identify this token GitHub does not report an owner for the token, so it is not stored. GH_TOKEN and GITHUB_TOKEN accept it

submilli skill installs the Submilli skill for a coding assistant, with a submilli-verifier subagent beside it. --agent picks the assistant. --project <dir> installs under that directory instead of the user’s home directory (HOME, or USERPROFILE on Windows).

--agent Skill directory Verifier
claude .claude/skills/submilli .claude/agents/submilli-verifier.md
codex .agents/skills/submilli .codex/agents/submilli-verifier.toml
cursor .cursor/skills/submilli .cursor/agents/submilli-verifier.md
…/.claude/skills/submilli: skill v5 from CLI 0.1.6 is installed. Restart your assistant to reload it.

The skill directory holds a receipt, .submilli-skill.json, with the installed files’ hashes. install and update write the skill bundled in the CLI, with no network access. update requires an existing installation. Neither replaces an installation whose files were edited, added, or removed. Such an installation is reported as locally modified; preserved, and there is no option to overwrite it. A symlink in the installation path is refused. status prints current, not installed, outdated; run submilli skill sync, or locally modified; preserved, and exits 1 for all but current.

sync takes no options. It finds every installation with a receipt under the home directory and in each directory from the current one up to the enclosing Git repository’s root, and updates each unmodified one to the newest skill release, skill-v<N> tags of the release repository. It checks for a release at most once a day, with a 5-second timeout, and falls back to the bundled skill when offline or when the bundled one is newer. A release that needs a newer CLI is not installed. Any other command run at a terminal prints a reminder when an installation differs from the CLI’s bundle.

submilli upgrade downloads the latest release, or the tag given with --version, for this platform. It verifies each executable against the release’s SHA-256 checksums and replaces both submilli and the submilli-server in the same directory. Both are verified and staged before either is replaced, so a failure changes nothing. It then runs submilli skill sync. Without --version it never moves to an older release. --check prints the latest release and exits 1 if it is newer than the running CLI, 0 otherwise.

Run a Submilli script in-process
Usage: submilli run [OPTIONS] <SCRIPT>
Arguments:
<SCRIPT>
Path to the `.ts` or `.subm` script to run
Options:
--fuel <FUEL>
Fuel budget. Defaults to the runtime's `RuntimeConfig::default()` value
--report
Print fuel, peak accounted memory, timings, and the run cost to stderr after execution
--max-stack <MAX_STACK>
Maximum wasm stack in bytes
--timeout <TIMEOUT>
Wall-clock deadline in milliseconds. Time spent waiting at an approval prompt doesn't
count. Omit for no deadline
--vfs <VFS>
Directory to expose as the script's VFS root. The future `submilli:fs.*` host functions
will resolve paths against it. Omit to allocate a fresh tempdir under the OS temp root for
the duration of the run
--blueprint <BLUEPRINT>
Apply a blueprint's policy (capability gating, deny-by-default) and `auth_proxy:` secret
injection to this local run. Without it, the run is unrestricted (allow-all). `store:`
secrets resolve from the local secret store, and authenticated `@mcp/<server>` servers are
called in-process — no running server needed. A call an `ask-human` or `ask-admin` rule
matches is asked about on the terminal: `y` approves, anything else denies. Without a
terminal to ask on, it is denied
--var <NAME=VALUE>
Bind a blueprint variable for this run, `NAME=VALUE` (repeatable), the way an application
binds it when it opens a session. Requires `--blueprint`; the blueprint must declare the
variable, and its `required` variables must all be bound
--max-llm-tokens <TOKENS>
Tokens this run's `submilli:llm` calls may spend in total. A run that asks for more raises
a catchable `QuotaExceededError` rather than being billed.
Finite by default, deliberately: a blueprint-configured provider spends real money against
the operator's credential, and a CLI run has no server-wide ceiling behind it. [default:
1000000] Env: `$SUBMILLI_MAX_EXECUTION_LLM_TOKENS`.
--max-llm-concurrency <PROMPTS>
Prompts one `llm.batch` or `llm.texts` dispatches at once. [default: 4] Env:
`$SUBMILLI_MAX_LLM_CONCURRENCY`
--max-execution-embedding-tokens <TOKENS>
Tokens this run's `submilli:embedding` calls may spend in total. A call that asks for more
raises a catchable `QuotaExceededError`. [default: 2000000] Env:
`$SUBMILLI_MAX_EXECUTION_EMBEDDING_TOKENS`, which outranks the config file
--max-execution-embedding-requests <REQUESTS>
Outbound provider requests this run's `submilli:embedding` calls may send. [default: 1000]
Env: `$SUBMILLI_MAX_EXECUTION_EMBEDDING_REQUESTS`, which outranks the config file
--max-embedding-concurrency <REQUESTS>
Provider requests one embedding call sends at once. [default: 4] Env:
`$SUBMILLI_MAX_EMBEDDING_CONCURRENCY`, which outranks the config file
-h, --help
Print help (see a summary with '-h')
Typecheck a Submilli script without running it
Usage: submilli check <SCRIPT>
Arguments:
<SCRIPT> Path to the `.subm` script to typecheck
Options:
-h, --help Print help
Scaffold, check, and publish a package project (submilli.toml)
Usage: submilli build <COMMAND>
Commands:
init Create a submilli.toml with a first package and scaffold its folders
new Add a new package to submilli.toml and scaffold its folders
check Compile the project's packages in dependency order without installing
publish-local Compile the project's packages and install them into the local store
test Compile and run the project's `tests/**/*.test.{ts,subm}` files
authority-map Compile packages and print their full authority call graph as JSON
security-review Review package authorization with Codex, Claude Code, or Copilot CLI
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
Create a submilli.toml with a first package and scaffold its folders
Usage: submilli build init [NAME] [PATH]
Arguments:
[NAME] First package name (`@scope/name`). Prompted on stdin when omitted
[PATH] First package path relative to submilli.toml. Defaults to `.`
Options:
-h, --help Print help
Add a new package to submilli.toml and scaffold its folders
Usage: submilli build new <NAME> <PATH>
Arguments:
<NAME> Package name (`@scope/name`)
<PATH> Package path relative to submilli.toml
Options:
-h, --help Print help
Compile the project's packages in dependency order without installing
Usage: submilli build check [OPTIONS]
Options:
--config <NAME=VALUE> Set a src/config.ts parameter of the explicitly selected package
-p, --package <PACKAGE> Compile only this package and its sibling dependencies
--deny-warnings Fail on code warnings; also enabled by SUBMILLI_DENY_WARNINGS=1
-h, --help Print help
Compile the project's packages and install them into the local store
Usage: submilli build publish-local [OPTIONS]
Options:
--config <NAME=VALUE> Set a src/config.ts parameter of the explicitly selected package
-p, --package <PACKAGE> Compile only this package and its sibling dependencies
--deny-warnings Fail on code warnings; also enabled by SUBMILLI_DENY_WARNINGS=1
-h, --help Print help
Compile and run the project's `tests/**/*.test.{ts,subm}` files
Usage: submilli build test [OPTIONS]
Options:
--config <NAME=VALUE> Set a src/config.ts parameter of the explicitly selected package
-p, --package <PACKAGE> Compile only this package and its sibling dependencies
--deny-warnings Fail on code warnings; also enabled by SUBMILLI_DENY_WARNINGS=1
--all-env Supply all Unicode process environment variables as test credentials
--env-var <NAME> Supply a process variable (repeatable or comma-separated); fail if
unset or non-Unicode
--env-file <PATH> Read credentials from a file; relative paths use the current directory.
Fail if unreadable
--skip-network Skip network.test.{ts,subm} and network_*.test.{ts,subm} anywhere under
tests/
-h, --help Print help
Tests receive no credentials by default. Credential precedence (highest first): --env-var >
--env-file > --all-env, regardless of argument order.
Compile packages and print their full authority call graph as JSON
Usage: submilli build authority-map [OPTIONS]
Options:
--config <NAME=VALUE> Set a src/config.ts parameter of the explicitly selected package
-p, --package <PACKAGE> Compile only this package and its sibling dependencies
--deny-warnings Fail on code warnings; also enabled by SUBMILLI_DENY_WARNINGS=1
-h, --help Print help
Review package authorization with Codex, Claude Code, or Copilot CLI
Usage: submilli build security-review [OPTIONS] --agent <AGENT> --model <MODEL>
Options:
--config <NAME=VALUE> Set a src/config.ts parameter of the explicitly selected package
-a, --agent <AGENT> Installed coding agent to invoke; uses its existing authentication
[possible values: codex, claude, copilot]
-m, --model <MODEL> Provider model ID; "astra" resolves to gpt-6-astra for Codex/Copilot
-e, --effort <EFFORT> Reasoning effort; the selected CLI/model must support it [possible
values: low, medium, high]
-p, --package <PACKAGE> Review this package and its local dependency closure; default: all
packages
--fail-on <FAIL_ON> Fail on findings at this severity or higher. Incomplete reviews always
fail [default: high] [possible values: low, medium, high, critical]
--output <FILE> Write a JSON report, including failures. Refuses to replace an existing
file
--timeout <TIMEOUT> Maximum time for the agent, in seconds (1–3600) [default: 600]
-h, --help Print help
Install a package from GitHub into the local store, pinned to a commit
Usage: submilli install [OPTIONS] <URL> [PACKAGE]
Arguments:
<URL> GitHub repo to install from: `org/repo`, `github.com/org/repo`, or a full URL —
optionally pinned with `@<ref>` (branch, tag, or commit SHA). A private repository
needs a GitHub token: see `submilli github authenticate`
[PACKAGE] Install only this package (`@org/name`). Omit to install every package the repo
declares
Options:
--config <NAME=VALUE> Set a src/config.ts parameter of the selected package
--reset-config <NAME> Remove a saved override and use the source default
--upgrade Replace an installed package when its source or configuration changes
--deny-warnings Fail on code warnings; also enabled by SUBMILLI_DENY_WARNINGS=1
-h, --help Print help
Print a stdlib package's declarations and description
Usage: submilli docs [OPTIONS] <NAME>
Arguments:
<NAME> Package name, e.g. `submilli:http` or an installed `@org/name`. A language built-in
(`Temporal`, `Temporal.Instant`) resolves here too
Options:
--blueprint <BLUEPRINT> Show only what programs under this blueprint could import. Without
it, the whole library is shown. An `@mcp/<server>` package is always
read from a blueprint, by default blueprint.yaml
-h, --help Print help
Search available stdlib packages by name, description, or symbol
Usage: submilli search [OPTIONS] [QUERY]
Arguments:
[QUERY] Substring to match against module names, descriptions, and exported symbols. Omit to list
every package
Options:
--blueprint <BLUEPRINT> List only what programs under this blueprint could import. Its
`@mcp/<server>` packages are not listed: read one with `submilli docs
@mcp/<server> --blueprint <path>`. Without it, the whole library is
listed
-h, --help Print help
Print declarations for language built-ins, or list the catalog
Usage: submilli builtins [NAMES]...
Arguments:
[NAMES]... Built-in names to describe, e.g. `Array Map Temporal`. A dotted member path
(`Temporal.Instant`) prints just that member. Omit to list the full catalog
Options:
-h, --help Print help
Install or update the Submilli coding-assistant skill
Usage: submilli skill <COMMAND>
Commands:
install Install the skill bundled with this CLI (no network required)
update Refresh an installed, unmodified skill from this CLI's bundle
status Check installation integrity and freshness; exit 1 if missing or different
sync Bring every unmodified installation for this user and project up to the newest released
skill. Falls back to this CLI's bundle when offline
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
Install the skill bundled with this CLI (no network required)
Usage: submilli skill install [OPTIONS] --agent <AGENT>
Options:
--agent <AGENT> Assistant whose discovery directory to use [possible values: claude,
codex, cursor]
--project <DIRECTORY> Install in this project instead of the user home directory
-h, --help Print help
Refresh an installed, unmodified skill from this CLI's bundle
Usage: submilli skill update [OPTIONS] --agent <AGENT>
Options:
--agent <AGENT> Assistant whose discovery directory to use [possible values: claude,
codex, cursor]
--project <DIRECTORY> Install in this project instead of the user home directory
-h, --help Print help
Check installation integrity and freshness; exit 1 if missing or different
Usage: submilli skill status [OPTIONS] --agent <AGENT>
Options:
--agent <AGENT> Assistant whose discovery directory to use [possible values: claude,
codex, cursor]
--project <DIRECTORY> Install in this project instead of the user home directory
-h, --help Print help
Bring every unmodified installation for this user and project up to the newest released skill. Falls
back to this CLI's bundle when offline
Usage: submilli skill sync
Options:
-h, --help Print help
Replace this executable with the latest published release
Usage: submilli upgrade [OPTIONS]
Options:
--version <TAG> Release tag to install (for example v0.2.0). Defaults to the latest release
--check Report the latest release without installing it; exit 1 if it is newer
-h, --help Print help
Author a blueprint file locally (scaffold, edit)
Usage: submilli blueprint <COMMAND>
Commands:
init Scaffold a minimal deny-by-default `blueprint.yaml` in the current directory
(`--full` lists every stdlib capability). Offline — no server needed
git Configure Git identity and HTTPS username in a local blueprint
lint Validate a blueprint file's syntax and references. Offline
add-mcp Add an outbound MCP server to a local `blueprint.yaml`
add-package Add an already-installed package to a local `blueprint.yaml`
variable Manage the session variables declared in a local `blueprint.yaml`'s `variables:`
block
secret Manage the secrets declared in a local `blueprint.yaml`'s `secrets:` block
auth-proxy Manage host-keyed outbound-auth rules in a local `blueprint.yaml`
capability Browse gateable capabilities and edit `permissions:` rules in a local
`blueprint.yaml`
prompt Print the LLM-facing `execute` tool description (the MCP "system prompt") for a
blueprint, with placeholders resolved as the server resolves them. Offline — no
server needed
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
Scaffold a minimal deny-by-default `blueprint.yaml` in the current directory (`--full` lists every
stdlib capability). Offline — no server needed
Usage: submilli blueprint init [OPTIONS] [NAME]
Arguments:
[NAME] Blueprint name (the `name:` field). Defaults to the target directory name
Options:
--blueprint <BLUEPRINT> Path to write (default: ./blueprint.yaml)
--full Scaffold every stdlib capability as a deny rule with a commented
filter example, instead of the minimal empty policy
-h, --help Print help
Configure Git identity and HTTPS username in a local blueprint
Usage: submilli blueprint git <COMMAND>
Commands:
set Enable or update Git. Values may contain declared ${vars.NAME} references
show Show Git templates and token declaration, never secret values
remove Disable Git without removing secrets, variables, or permissions
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
Enable or update Git. Values may contain declared ${vars.NAME} references
Usage: submilli blueprint git set [OPTIONS] --name <NAME> --email <EMAIL>
Options:
--name <NAME>
--email <EMAIL>
--username <USERNAME>
--clear-username
--blueprint <BLUEPRINT>
-h, --help Print help
Show Git templates and token declaration, never secret values
Usage: submilli blueprint git show [OPTIONS]
Options:
--blueprint <BLUEPRINT>
-h, --help Print help
Disable Git without removing secrets, variables, or permissions
Usage: submilli blueprint git remove [OPTIONS]
Options:
--blueprint <BLUEPRINT>
-h, --help Print help
Validate a blueprint file's syntax and references. Offline
Usage: submilli blueprint lint [OPTIONS] <FILE>
Arguments:
<FILE> Path to the blueprint YAML file to lint
Options:
--fix Add the rules declared packages and their dependencies require for their own
calls
--deny-warnings Fail on blueprint warnings; also enabled by SUBMILLI_DENY_WARNINGS=1
-h, --help Print help
Add an outbound MCP server to a local `blueprint.yaml`
Usage: submilli blueprint add-mcp [OPTIONS] <NAME> <URL>
Arguments:
<NAME> Local identifier for the server: its key in the `mcp:` block and the import name
`@mcp/<name>`
<URL> The MCP endpoint URL
Options:
--blueprint <BLUEPRINT>
Blueprint file to edit (default: ./blueprint.yaml)
--oauth
Make this an OAuth server (`auth: type: oauth2`). A client id isn't required — the CLI
does Dynamic Client Registration at authenticate time
--client-id <CLIENT_ID>
OAuth client id, for servers that need a pre-registered client. Implies `--oauth`. A
literal or a `${secrets.X}` reference
--scope <SCOPES>
OAuth scope to request (repeatable). Implies `--oauth`
--header <HEADERS>
Static request header, `"Name: value"` (repeatable). Use `${secrets.X}` for credentials.
Conflicts with the OAuth flags
--authorization-bearer <SECRET_NAME>
Shorthand for static API-key auth: sets the header `Authorization: Bearer
${secrets.<NAME>}`. The secret must already be declared (`submilli blueprint secret add`).
Implies static auth, so the OAuth probe is skipped. Conflicts with the OAuth flags
--no-probe
Skip the network probe that auto-detects whether the server needs OAuth
-h, --help
Print help
Add an already-installed package to a local `blueprint.yaml`
Usage: submilli blueprint add-package [OPTIONS] <PACKAGE>
Arguments:
<PACKAGE> Package name to add, e.g. `@stripe/sdk`. The packages it depends on get caller rules
too
Options:
--capabilities <NAME,...> Provided capabilities to allow for `main`, comma-separated
--all-capabilities Allow every capability the package provides
--no-capabilities Allow none of the provided capabilities (the blueprint's `default:`
decides them; under `default: allow` they get explicit `deny`
rules)
--blueprint <BLUEPRINT> Blueprint file to edit (default: ./blueprint.yaml)
-h, --help Print help
Manage the session variables declared in a local `blueprint.yaml`'s `variables:` block
Usage: submilli blueprint variable <COMMAND>
Commands:
add Declare a session variable in the `variables:` block
list List the blueprint's declared variables
remove Remove a declared variable. Refused while a permission filter still references it
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
Declare a session variable in the `variables:` block
Usage: submilli blueprint variable add [OPTIONS] <NAME>
Arguments:
<NAME> Variable name — what `${vars.<NAME>}` references in a filter
Options:
--required Reject a session that omits the variable or binds it to an empty
string
--default <VALUE> Value bound when the caller supplies none. A variable is always a
string
--alias <NAME> Resolve from another declared variable instead of accepting a binding
--blueprint <BLUEPRINT> Blueprint file to edit (default: ./blueprint.yaml)
-h, --help Print help
List the blueprint's declared variables
Usage: submilli blueprint variable list [OPTIONS]
Options:
--blueprint <BLUEPRINT> Blueprint file to read (default: ./blueprint.yaml)
-h, --help Print help
Remove a declared variable. Refused while a permission filter still references it
Usage: submilli blueprint variable remove [OPTIONS] <NAME>
Arguments:
<NAME> The variable to remove
Options:
--blueprint <BLUEPRINT> Blueprint file to edit (default: ./blueprint.yaml)
-h, --help Print help
Manage the secrets declared in a local `blueprint.yaml`'s `secrets:` block
Usage: submilli blueprint secret <COMMAND>
Commands:
add Declare a secret in the blueprint's `secrets:` block
list List the blueprint's declared secrets and their sources (never values)
remove Remove a declared secret. Refused while `auth_proxy:`, `mcp:`, `llm:`, or `embedding:`
still references it
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
Declare a secret in the blueprint's `secrets:` block
Usage: submilli blueprint secret add [OPTIONS] <--store <KEY>|--harness> <NAME>
Arguments:
<NAME> Secret name — what `${secrets.<NAME>}` references
Options:
--store <KEY> Read the value from the server's SecretStore under this key
--harness Bind the value from the trusted harness separately for each session
--required Reject session creation or rebind when the harness value is absent
--blueprint <BLUEPRINT> Blueprint file to edit (default: ./blueprint.yaml)
-h, --help Print help
List the blueprint's declared secrets and their sources (never values)
Usage: submilli blueprint secret list [OPTIONS]
Options:
--blueprint <BLUEPRINT> Blueprint file to read (default: ./blueprint.yaml)
-h, --help Print help
Remove a declared secret. Refused while `auth_proxy:`, `mcp:`, `llm:`, or `embedding:` still
references it
Usage: submilli blueprint secret remove [OPTIONS] <NAME>
Arguments:
<NAME> The secret to remove
Options:
--blueprint <BLUEPRINT> Blueprint file to edit (default: ./blueprint.yaml)
-h, --help Print help
Manage host-keyed outbound-auth rules in a local `blueprint.yaml`
Usage: submilli blueprint auth-proxy <COMMAND>
Commands:
add Add a host-keyed auth-injection rule to the `auth_proxy:` block
list List the blueprint's auth-proxy rules (never prints secret values)
remove Remove the auth-proxy rule for a host
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
Add a host-keyed auth-injection rule to the `auth_proxy:` block
Usage: submilli blueprint auth-proxy add [OPTIONS] --host <HOST> <--bearer <SECRET_NAME>|--basic-username <USERNAME>|--header <NAME=VALUE>|--query <KEY=VALUE>>
Options:
--host <HOST> Destination host to match exactly (e.g. `api.github.com`)
--allow-insecure-http Permit HTTP for this rule; the blueprint must separately
allow_insecure_http
--bearer <SECRET_NAME> Bearer-token auth: names a declared secret. Sets
`Authorization: Bearer <secret>`
--basic-username <USERNAME> Basic-auth username (a literal, not a secret). Requires
`--basic-password`
--basic-password <SECRET_NAME> Basic-auth password: names a declared secret. Requires
`--basic-username`
--header <NAME=VALUE> Raw header injection, `Name=value` (repeatable). Value may use
`${secrets.X}`
--query <KEY=VALUE> Raw query-param injection, `key=value` (repeatable). Value may
use `${secrets.X}`
--blueprint <BLUEPRINT> Blueprint file to edit (default: ./blueprint.yaml)
-h, --help Print help
List the blueprint's auth-proxy rules (never prints secret values)
Usage: submilli blueprint auth-proxy list [OPTIONS]
Options:
--blueprint <BLUEPRINT> Blueprint file to read (default: ./blueprint.yaml)
-h, --help Print help
Remove the auth-proxy rule for a host
Usage: submilli blueprint auth-proxy remove [OPTIONS] --host <HOST>
Options:
--host <HOST> The rule's host to remove
--blueprint <BLUEPRINT> Blueprint file to edit (default: ./blueprint.yaml)
-h, --help Print help
Browse gateable capabilities and edit `permissions:` rules in a local `blueprint.yaml`
Usage: submilli blueprint capability <COMMAND>
Commands:
list List the capabilities available to the blueprint, annotated with the permission rules
already present. Offline — no server needed
add Append a permission rule to the `permissions:` block. Rewrites the file; YAML comments are
not preserved
remove Remove every rule for a capability. Rewrites the file; YAML comments are not preserved
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
List the capabilities available to the blueprint, annotated with the permission rules already
present. Offline — no server needed
Usage: submilli blueprint capability list [OPTIONS] [LIBRARY]
Arguments:
[LIBRARY] Show one library only: a stdlib module (`submilli:fs`), a declared package or a package
one depends on, or a declared MCP server name
Options:
--blueprint <BLUEPRINT> Blueprint file to read (default: ./blueprint.yaml). Without a
readable blueprint the stdlib catalog is still listed
--unconfigured Show only the capabilities declared packages provide that have no
rule under `main` (a filtered rule or a `deny` counts as a rule), and
the default they fall through to. Requires a readable blueprint
-h, --help Print help
Append a permission rule to the `permissions:` block. Rewrites the file; YAML comments are not
preserved
Usage: submilli blueprint capability add [OPTIONS] <CAPABILITY>
Arguments:
<CAPABILITY> Capability name, e.g. `fs.read` or `mcp.linear`
Options:
--action <ACTION> The rule's action. Adding a capability under `default: deny` grants
it, so the default is `allow` [default: allow] [possible values:
allow, deny, ask-human, ask-admin]
--filter <FILTER> Filter expression constraining the rule, e.g. 'path glob "*.csv"'
--caller <CALLER> Caller id the rule applies to (`main` is the user script; a package
name gates that package's own calls) [default: main]
--force Add the rule even if the capability name isn't known to the stdlib
catalog, a declared package, or a declared MCP server
--blueprint <BLUEPRINT> Blueprint file to edit (default: ./blueprint.yaml)
-h, --help Print help
Remove every rule for a capability. Rewrites the file; YAML comments are not preserved
Usage: submilli blueprint capability remove [OPTIONS] <CAPABILITY>
Arguments:
<CAPABILITY> Capability name whose rules to remove
Options:
--caller <CALLER> Caller id to remove the rules from [default: main]
--blueprint <BLUEPRINT> Blueprint file to edit (default: ./blueprint.yaml)
-h, --help Print help
Print the LLM-facing `execute` tool description (the MCP "system prompt") for a blueprint, with
placeholders resolved as the server resolves them. Offline — no server needed
Usage: submilli blueprint prompt [OPTIONS]
Options:
--blueprint <BLUEPRINT> Blueprint whose policy resolves `{vfs_mode}` / `{http_access}`.
Defaults to `./blueprint.yaml` if present, otherwise an empty
(deny-all) policy
-h, --help Print help
Manage secrets in the local secret store (no running server)
Usage: submilli secret <COMMAND>
Commands:
put Store a secret; prompts for the value, or reads it from piped stdin
delete Delete a secret by key
list List secret keys, optionally filtered by prefix
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
Store a secret; prompts for the value, or reads it from piped stdin
Usage: submilli secret put <KEY>
Arguments:
<KEY>
Options:
-h, --help Print help
Delete a secret by key
Usage: submilli secret delete <KEY>
Arguments:
<KEY>
Options:
-h, --help Print help
List secret keys, optionally filtered by prefix
Usage: submilli secret list [OPTIONS]
Options:
--prefix <PREFIX> Only list keys starting with this prefix
-h, --help Print help
Authenticate outbound OAuth MCP servers locally (no running server)
Usage: submilli mcp <COMMAND>
Commands:
authenticate Run the OAuth flow for a blueprint's MCP server and store its credential locally.
Re-run to re-authenticate (e.g. after changing scopes) — it overwrites the
existing credential
deauthenticate Remove an MCP server's stored credential (blueprint returns to PENDING)
auth-status Show each declared MCP server's authentication state
grants List the MCP OAuth grants stored locally, one per blueprint and server
provider Manage local OAuth provider apps (`~/.submilli/mcp_oauth.yaml`) — the client id /
secret used to authenticate confidential OAuth servers
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
Run the OAuth flow for a blueprint's MCP server and store its credential locally. Re-run to
re-authenticate (e.g. after changing scopes) — it overwrites the existing credential
Usage: submilli mcp authenticate --blueprint <BLUEPRINT> <SERVER>
Arguments:
<SERVER> The MCP server's local name (its key in the blueprint's `mcp:` block)
Options:
--blueprint <BLUEPRINT> Blueprint file that declares the MCP server
-h, --help Print help
Remove an MCP server's stored credential (blueprint returns to PENDING)
Usage: submilli mcp deauthenticate --blueprint <BLUEPRINT> <SERVER>
Arguments:
<SERVER> The MCP server's local name (its key in the blueprint's `mcp:` block)
Options:
--blueprint <BLUEPRINT> Blueprint file that declares the MCP server
-h, --help Print help
Show each declared MCP server's authentication state
Usage: submilli mcp auth-status --blueprint <BLUEPRINT>
Options:
--blueprint <BLUEPRINT> Blueprint file to report on
-h, --help Print help
List the MCP OAuth grants stored locally, one per blueprint and server
Usage: submilli mcp grants [OPTIONS]
Options:
--blueprint <BLUEPRINT> Only list this blueprint's grants
-h, --help Print help
Manage local OAuth provider apps (`~/.submilli/mcp_oauth.yaml`) — the client id / secret used to
authenticate confidential OAuth servers
Usage: submilli mcp provider <COMMAND>
Commands:
add Add or replace the provider matching a host
list List configured providers (secret references are shown; values are not)
remove Remove the provider matching a host
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
Add or replace the provider matching a host
Usage: submilli mcp provider add [OPTIONS] --match <MATCH_HOST> --client-id <CLIENT_ID>
Options:
--match <MATCH_HOST> OAuth host to match (e.g. `github.com`), compared against the
token endpoint's host — not the MCP URL
--client-id <CLIENT_ID> OAuth client id. A literal, or a `${secrets.X}` / `${env.X}`
reference
--client-secret <CLIENT_SECRET> OAuth client secret, as a reference: `${secrets.NAME}` (from
the local store) or `${env.VAR}`. Omit for a public
(PKCE-only) client
--scope <SCOPES> OAuth scope to request (repeatable)
-h, --help Print help
List configured providers (secret references are shown; values are not)
Usage: submilli mcp provider list
Options:
-h, --help Print help
Remove the provider matching a host
Usage: submilli mcp provider remove --match <MATCH_HOST>
Options:
--match <MATCH_HOST> The `match` host of the provider to remove
-h, --help Print help
Manage the GitHub token used to install packages from private repositories
Usage: submilli github <COMMAND>
Commands:
authenticate Store a GitHub token for installing packages from private repositories. Prompts
for it, or reads it from piped stdin. It needs Repository permissions → Contents:
Read-only on the package repositories (a fine-grained token), or the `repo` scope
(a classic token)
deauthenticate Remove the stored GitHub token
auth-status Show which GitHub token package fetches use, and whose it is
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
Store a GitHub token for installing packages from private repositories. Prompts for it, or reads it
from piped stdin. It needs Repository permissions → Contents: Read-only on the package repositories
(a fine-grained token), or the `repo` scope (a classic token)
Usage: submilli github authenticate [OPTIONS]
Options:
--owner <OWNER> The user or organization whose repositories the token is for; fills it in on
the token-creation link
-h, --help Print help
Remove the stored GitHub token
Usage: submilli github deauthenticate
Options:
-h, --help Print help
Show which GitHub token package fetches use, and whose it is
Usage: submilli github auth-status
Options:
-h, --help Print help
Interact with a running submilli-server
Usage: submilli server <COMMAND>
Commands:
runs Inspect executions and resume stuck runs
approval Decide calls waiting for approval (`ask-admin`, `ask-human`)
apply Apply blueprint YAML documents to a running submilli-server
trust Manage approved HTTPS server public keys
docs Read package declarations, including a blueprint's MCP tools
run-code Execute a Submilli script on a running submilli-server
packages Manage the server's package store and list the packages it can resolve
status Report a running server's status (pid, bind, sessions, blueprints)
stop Ask a running server to drain and stop
blueprint Manage blueprints registered on the server
secret Manage secrets in the server's secret store
session Open and close sessions, for `run-code --session`
mcp Authenticate outbound OAuth MCP servers declared in a blueprint
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
Inspect executions and resume stuck runs
Usage: submilli server runs <COMMAND>
Commands:
list List runs, including stuck runs and their reasons
show Inspect a run and its retained result
resume Resume a stuck run with its original code, identity, and limits
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
List runs, including stuck runs and their reasons
Usage: submilli server runs list [OPTIONS]
Options:
--session <SESSION>
--status <STATUS> [possible values: queued, running, stuck, completed, cancelled, aborted,
indeterminate, expired]
--json
--server <URL> Base URL of the running submilli-server [env: SUBMILLI_SERVER_URL=]
[default: http://127.0.0.1:8128]
--token-file <PATH> File holding the API token to send. Without it the token is read from
`$SUBMILLI_SERVER_TOKEN`; with neither, no token is sent, which only a
server started with `--allow-unauthenticated` accepts. There is no flag
taking the token itself, so it never lands in the process list. Env:
`$SUBMILLI_SERVER_TOKEN_FILE`
-h, --help Print help
Inspect a run and its retained result
Usage: submilli server runs show [OPTIONS] <RUN_ID>
Arguments:
<RUN_ID>
Options:
--json
--server <URL> Base URL of the running submilli-server [env: SUBMILLI_SERVER_URL=]
[default: http://127.0.0.1:8128]
--token-file <PATH> File holding the API token to send. Without it the token is read from
`$SUBMILLI_SERVER_TOKEN`; with neither, no token is sent, which only a
server started with `--allow-unauthenticated` accepts. There is no flag
taking the token itself, so it never lands in the process list. Env:
`$SUBMILLI_SERVER_TOKEN_FILE`
-h, --help Print help
Resume a stuck run with its original code, identity, and limits
Usage: submilli server runs resume [OPTIONS] <RUN_ID>
Arguments:
<RUN_ID>
Options:
--json
--server <URL> Base URL of the running submilli-server [env: SUBMILLI_SERVER_URL=]
[default: http://127.0.0.1:8128]
--token-file <PATH> File holding the API token to send. Without it the token is read from
`$SUBMILLI_SERVER_TOKEN`; with neither, no token is sent, which only a
server started with `--allow-unauthenticated` accepts. There is no flag
taking the token itself, so it never lands in the process list. Env:
`$SUBMILLI_SERVER_TOKEN_FILE`
-h, --help Print help
Decide calls waiting for approval (`ask-admin`, `ask-human`)
Usage: submilli server approval <COMMAND>
Commands:
list List calls waiting for approval, oldest first
show Show one call waiting for approval: what it does, the rule that asked, and its session
approve Approve a waiting call: it runs, and the program carries on
deny Deny a waiting call: the program's call throws `PermissionDeniedError`
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
List calls waiting for approval, oldest first
Usage: submilli server approval list [OPTIONS]
Options:
--approver <APPROVER> Only calls waiting for this approver [possible values: human, admin]
--session <SESSION> Only calls of this session
--json
--server <URL> Base URL of the running submilli-server [env: SUBMILLI_SERVER_URL=]
[default: http://127.0.0.1:8128]
--token-file <PATH> File holding the API token to send. Without it the token is read from
`$SUBMILLI_SERVER_TOKEN`; with neither, no token is sent, which only a
server started with `--allow-unauthenticated` accepts. There is no flag
taking the token itself, so it never lands in the process list. Env:
`$SUBMILLI_SERVER_TOKEN_FILE`
-h, --help Print help
Show one call waiting for approval: what it does, the rule that asked, and its session
Usage: submilli server approval show [OPTIONS] <CALL_ID>
Arguments:
<CALL_ID> The call's id, as `list` shows it
Options:
--json
--server <URL> Base URL of the running submilli-server [env: SUBMILLI_SERVER_URL=]
[default: http://127.0.0.1:8128]
--token-file <PATH> File holding the API token to send. Without it the token is read from
`$SUBMILLI_SERVER_TOKEN`; with neither, no token is sent, which only a
server started with `--allow-unauthenticated` accepts. There is no flag
taking the token itself, so it never lands in the process list. Env:
`$SUBMILLI_SERVER_TOKEN_FILE`
-h, --help Print help
Approve a waiting call: it runs, and the program carries on
Usage: submilli server approval approve [OPTIONS] <CALL_ID>
Arguments:
<CALL_ID> The call's id, as `list` shows it
Options:
--reason <REASON> Why. A denial's reason reaches the program
--json
--server <URL> Base URL of the running submilli-server [env: SUBMILLI_SERVER_URL=]
[default: http://127.0.0.1:8128]
--token-file <PATH> File holding the API token to send. Without it the token is read from
`$SUBMILLI_SERVER_TOKEN`; with neither, no token is sent, which only a
server started with `--allow-unauthenticated` accepts. There is no flag
taking the token itself, so it never lands in the process list. Env:
`$SUBMILLI_SERVER_TOKEN_FILE`
-h, --help Print help
Deny a waiting call: the program's call throws `PermissionDeniedError`
Usage: submilli server approval deny [OPTIONS] <CALL_ID>
Arguments:
<CALL_ID> The call's id, as `list` shows it
Options:
--reason <REASON> Why. A denial's reason reaches the program
--json
--server <URL> Base URL of the running submilli-server [env: SUBMILLI_SERVER_URL=]
[default: http://127.0.0.1:8128]
--token-file <PATH> File holding the API token to send. Without it the token is read from
`$SUBMILLI_SERVER_TOKEN`; with neither, no token is sent, which only a
server started with `--allow-unauthenticated` accepts. There is no flag
taking the token itself, so it never lands in the process list. Env:
`$SUBMILLI_SERVER_TOKEN_FILE`
-h, --help Print help
Apply blueprint YAML documents to a running submilli-server
Usage: submilli server apply [OPTIONS] --file <FILE>
Options:
-f, --file <FILE> YAML file (multi-document ok) or directory of .yaml files to apply
--server <URL> Base URL of the running submilli-server [env: SUBMILLI_SERVER_URL=]
[default: http://127.0.0.1:8128]
--token-file <PATH> File holding the API token to send. Without it the token is read from
`$SUBMILLI_SERVER_TOKEN`; with neither, no token is sent, which only a
server started with `--allow-unauthenticated` accepts. There is no flag
taking the token itself, so it never lands in the process list. Env:
`$SUBMILLI_SERVER_TOKEN_FILE`
-h, --help Print help
Manage approved HTTPS server public keys
Usage: submilli server trust <COMMAND>
Commands:
add Inspect and approve a server public key. No token is sent
list List approved server public keys in this Submilli home
remove Remove a saved public key before approving a verified replacement
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
Inspect and approve a server public key. No token is sent
Usage: submilli server trust add [OPTIONS] --server <URL>
Options:
--server <URL> HTTPS server URL whose public key should be approved [env:
SUBMILLI_SERVER_URL=]
--fingerprint <SHA256> Independently obtained SHA-256 SPKI fingerprint (sha256:<64 hex
digits>). Matching it approves trust without an interactive prompt
-h, --help Print help
List approved server public keys in this Submilli home
Usage: submilli server trust list
Options:
-h, --help Print help
Remove a saved public key before approving a verified replacement
Usage: submilli server trust remove --server <URL>
Options:
--server <URL> HTTPS server URL whose saved key should be removed [env: SUBMILLI_SERVER_URL=]
-h, --help Print help
Read package declarations, including a blueprint's MCP tools
Usage: submilli server docs [OPTIONS] --blueprint <BLUEPRINT> <NAME>
Arguments:
<NAME> Package name, including `@mcp/<server>` virtual packages
Options:
--blueprint <BLUEPRINT> Registered blueprint whose package catalog to query
--server <URL> Base URL of the running submilli-server [env: SUBMILLI_SERVER_URL=]
[default: http://127.0.0.1:8128]
--token-file <PATH> File holding the API token to send. Without it the token is read from
`$SUBMILLI_SERVER_TOKEN`; with neither, no token is sent, which only
a server started with `--allow-unauthenticated` accepts. There is no
flag taking the token itself, so it never lands in the process list.
Env: `$SUBMILLI_SERVER_TOKEN_FILE`
-h, --help Print help
Execute a Submilli script on a running submilli-server
Usage: submilli server run-code [OPTIONS] <SCRIPT>
Arguments:
<SCRIPT>
Options:
--blueprint <BLUEPRINT> Run in a fresh session bound to this registered blueprint
--session <SESSION> Run inside a session opened by `submilli server session open`, which
keeps its blueprint, variables, files, and session state between runs
--server <URL> Base URL of the running submilli-server [env: SUBMILLI_SERVER_URL=]
[default: http://127.0.0.1:8128]
--token-file <PATH> File holding the API token to send. Without it the token is read from
`$SUBMILLI_SERVER_TOKEN`; with neither, no token is sent, which only
a server started with `--allow-unauthenticated` accepts. There is no
flag taking the token itself, so it never lands in the process list.
Env: `$SUBMILLI_SERVER_TOKEN_FILE`
--var <NAME=VALUE> Bind a blueprint variable for this run, `NAME=VALUE` (repeatable),
the way an application binds it when it opens a session
--timeout <TIMEOUT> Omit for no client-side timeout; the server still enforces its own
fuel/epoch limits
-h, --help Print help
Manage the server's package store and list the packages it can resolve
Usage: submilli server packages <COMMAND>
Commands:
install Install a GitHub package into the server's store
list List the packages the server can resolve, marking any read from a fallback store
uninstall Remove an installed package from the server's store
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
Install a GitHub package into the server's store
Usage: submilli server packages install [OPTIONS] <URL> [PACKAGE]
Arguments:
<URL> GitHub repo: `org/repo`, `github.com/org/repo`, or a full URL. A private repository
needs the server's own GitHub token (`github_token_file` in its config file); this
command never sends yours
[PACKAGE] Install only this package (`@org/name`). Omit to install every package the repo
declares
Options:
--config <NAME=VALUE> Set a src/config.ts parameter of the selected package
--reset-config <NAME> Remove a saved override and use the source default
--sha <SHA> Pin to this commit SHA (or ref). Resolved from the default branch when
omitted
--upgrade Replace an installed package when its source or configuration changes
--deny-warnings Fail on code warnings; also enabled by SUBMILLI_DENY_WARNINGS=1
--server <URL> Base URL of the running submilli-server [env: SUBMILLI_SERVER_URL=]
[default: http://127.0.0.1:8128]
--token-file <PATH> File holding the API token to send. Without it the token is read from
`$SUBMILLI_SERVER_TOKEN`; with neither, no token is sent, which only a
server started with `--allow-unauthenticated` accepts. There is no flag
taking the token itself, so it never lands in the process list. Env:
`$SUBMILLI_SERVER_TOKEN_FILE`
-h, --help Print help
List the packages the server can resolve, marking any read from a fallback store
Usage: submilli server packages list [OPTIONS]
Options:
--server <URL> Base URL of the running submilli-server [env: SUBMILLI_SERVER_URL=]
[default: http://127.0.0.1:8128]
--token-file <PATH> File holding the API token to send. Without it the token is read from
`$SUBMILLI_SERVER_TOKEN`; with neither, no token is sent, which only a
server started with `--allow-unauthenticated` accepts. There is no flag
taking the token itself, so it never lands in the process list. Env:
`$SUBMILLI_SERVER_TOKEN_FILE`
-h, --help Print help
Remove an installed package from the server's store
Usage: submilli server packages uninstall [OPTIONS] <NAME>
Arguments:
<NAME> Package to remove, e.g. `@submilli/jina`
Options:
--server <URL> Base URL of the running submilli-server [env: SUBMILLI_SERVER_URL=]
[default: http://127.0.0.1:8128]
--token-file <PATH> File holding the API token to send. Without it the token is read from
`$SUBMILLI_SERVER_TOKEN`; with neither, no token is sent, which only a
server started with `--allow-unauthenticated` accepts. There is no flag
taking the token itself, so it never lands in the process list. Env:
`$SUBMILLI_SERVER_TOKEN_FILE`
-h, --help Print help
Report a running server's status (pid, bind, sessions, blueprints)
Usage: submilli server status [OPTIONS]
Options:
--server <URL> Base URL of the running submilli-server [env: SUBMILLI_SERVER_URL=]
[default: http://127.0.0.1:8128]
--token-file <PATH> File holding the API token to send. Without it the token is read from
`$SUBMILLI_SERVER_TOKEN`; with neither, no token is sent, which only a
server started with `--allow-unauthenticated` accepts. There is no flag
taking the token itself, so it never lands in the process list. Env:
`$SUBMILLI_SERVER_TOKEN_FILE`
-h, --help Print help
Ask a running server to drain and stop
Usage: submilli server stop [OPTIONS]
Options:
--server <URL> Base URL of the running submilli-server [env: SUBMILLI_SERVER_URL=]
[default: http://127.0.0.1:8128]
--token-file <PATH> File holding the API token to send. Without it the token is read from
`$SUBMILLI_SERVER_TOKEN`; with neither, no token is sent, which only a
server started with `--allow-unauthenticated` accepts. There is no flag
taking the token itself, so it never lands in the process list. Env:
`$SUBMILLI_SERVER_TOKEN_FILE`
-h, --help Print help
Manage blueprints registered on the server
Usage: submilli server blueprint <COMMAND>
Commands:
add Register a new blueprint file with the server; fails if the name is taken
apply Register a blueprint file, replacing any existing one with the same name
list List blueprints registered on the server
show Print a registered blueprint's YAML
remove Unregister a blueprint by name
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
Register a new blueprint file with the server; fails if the name is taken
Usage: submilli server blueprint add [OPTIONS] <FILE>
Arguments:
<FILE>
Options:
--server <URL> Base URL of the running submilli-server [env: SUBMILLI_SERVER_URL=]
[default: http://127.0.0.1:8128]
--token-file <PATH> File holding the API token to send. Without it the token is read from
`$SUBMILLI_SERVER_TOKEN`; with neither, no token is sent, which only a
server started with `--allow-unauthenticated` accepts. There is no flag
taking the token itself, so it never lands in the process list. Env:
`$SUBMILLI_SERVER_TOKEN_FILE`
-h, --help Print help
Register a blueprint file, replacing any existing one with the same name
Usage: submilli server blueprint apply [OPTIONS] <FILE>
Arguments:
<FILE>
Options:
--server <URL> Base URL of the running submilli-server [env: SUBMILLI_SERVER_URL=]
[default: http://127.0.0.1:8128]
--token-file <PATH> File holding the API token to send. Without it the token is read from
`$SUBMILLI_SERVER_TOKEN`; with neither, no token is sent, which only a
server started with `--allow-unauthenticated` accepts. There is no flag
taking the token itself, so it never lands in the process list. Env:
`$SUBMILLI_SERVER_TOKEN_FILE`
-h, --help Print help
List blueprints registered on the server
Usage: submilli server blueprint list [OPTIONS]
Options:
--server <URL> Base URL of the running submilli-server [env: SUBMILLI_SERVER_URL=]
[default: http://127.0.0.1:8128]
--token-file <PATH> File holding the API token to send. Without it the token is read from
`$SUBMILLI_SERVER_TOKEN`; with neither, no token is sent, which only a
server started with `--allow-unauthenticated` accepts. There is no flag
taking the token itself, so it never lands in the process list. Env:
`$SUBMILLI_SERVER_TOKEN_FILE`
-h, --help Print help
Print a registered blueprint's YAML
Usage: submilli server blueprint show [OPTIONS] <NAME>
Arguments:
<NAME>
Options:
--server <URL> Base URL of the running submilli-server [env: SUBMILLI_SERVER_URL=]
[default: http://127.0.0.1:8128]
--token-file <PATH> File holding the API token to send. Without it the token is read from
`$SUBMILLI_SERVER_TOKEN`; with neither, no token is sent, which only a
server started with `--allow-unauthenticated` accepts. There is no flag
taking the token itself, so it never lands in the process list. Env:
`$SUBMILLI_SERVER_TOKEN_FILE`
-h, --help Print help
Unregister a blueprint by name
Usage: submilli server blueprint remove [OPTIONS] <NAME>
Arguments:
<NAME>
Options:
--server <URL> Base URL of the running submilli-server [env: SUBMILLI_SERVER_URL=]
[default: http://127.0.0.1:8128]
--token-file <PATH> File holding the API token to send. Without it the token is read from
`$SUBMILLI_SERVER_TOKEN`; with neither, no token is sent, which only a
server started with `--allow-unauthenticated` accepts. There is no flag
taking the token itself, so it never lands in the process list. Env:
`$SUBMILLI_SERVER_TOKEN_FILE`
-h, --help Print help
Manage secrets in the server's secret store
Usage: submilli server secret <COMMAND>
Commands:
put Store a secret; prompts for the value, or reads it from piped stdin
delete Delete a secret by key
list List secret keys, optionally filtered by prefix
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
Store a secret; prompts for the value, or reads it from piped stdin
Usage: submilli server secret put [OPTIONS] <KEY>
Arguments:
<KEY>
Options:
--server <URL> Base URL of the running submilli-server [env: SUBMILLI_SERVER_URL=]
[default: http://127.0.0.1:8128]
--token-file <PATH> File holding the API token to send. Without it the token is read from
`$SUBMILLI_SERVER_TOKEN`; with neither, no token is sent, which only a
server started with `--allow-unauthenticated` accepts. There is no flag
taking the token itself, so it never lands in the process list. Env:
`$SUBMILLI_SERVER_TOKEN_FILE`
-h, --help Print help
Delete a secret by key
Usage: submilli server secret delete [OPTIONS] <KEY>
Arguments:
<KEY>
Options:
--server <URL> Base URL of the running submilli-server [env: SUBMILLI_SERVER_URL=]
[default: http://127.0.0.1:8128]
--token-file <PATH> File holding the API token to send. Without it the token is read from
`$SUBMILLI_SERVER_TOKEN`; with neither, no token is sent, which only a
server started with `--allow-unauthenticated` accepts. There is no flag
taking the token itself, so it never lands in the process list. Env:
`$SUBMILLI_SERVER_TOKEN_FILE`
-h, --help Print help
List secret keys, optionally filtered by prefix
Usage: submilli server secret list [OPTIONS]
Options:
--prefix <PREFIX> Only list keys starting with this prefix
--server <URL> Base URL of the running submilli-server [env: SUBMILLI_SERVER_URL=]
[default: http://127.0.0.1:8128]
--token-file <PATH> File holding the API token to send. Without it the token is read from
`$SUBMILLI_SERVER_TOKEN`; with neither, no token is sent, which only a
server started with `--allow-unauthenticated` accepts. There is no flag
taking the token itself, so it never lands in the process list. Env:
`$SUBMILLI_SERVER_TOKEN_FILE`
-h, --help Print help
Open and close sessions, for `run-code --session`
Usage: submilli server session <COMMAND>
Commands:
open Open a session bound to a registered blueprint and print its id
close Close a session, discarding its files and session state
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
Open a session bound to a registered blueprint and print its id
Usage: submilli server session open [OPTIONS] --blueprint <BLUEPRINT>
Options:
--blueprint <BLUEPRINT> Name of a blueprint registered on the server
--var <NAME=VALUE> Bind a blueprint variable for the whole session, `NAME=VALUE`
(repeatable)
--server <URL> Base URL of the running submilli-server [env: SUBMILLI_SERVER_URL=]
[default: http://127.0.0.1:8128]
--token-file <PATH> File holding the API token to send. Without it the token is read from
`$SUBMILLI_SERVER_TOKEN`; with neither, no token is sent, which only
a server started with `--allow-unauthenticated` accepts. There is no
flag taking the token itself, so it never lands in the process list.
Env: `$SUBMILLI_SERVER_TOKEN_FILE`
-h, --help Print help
Close a session, discarding its files and session state
Usage: submilli server session close [OPTIONS] <SESSION>
Arguments:
<SESSION> Id printed by `submilli server session open`
Options:
--server <URL> Base URL of the running submilli-server [env: SUBMILLI_SERVER_URL=]
[default: http://127.0.0.1:8128]
--token-file <PATH> File holding the API token to send. Without it the token is read from
`$SUBMILLI_SERVER_TOKEN`; with neither, no token is sent, which only a
server started with `--allow-unauthenticated` accepts. There is no flag
taking the token itself, so it never lands in the process list. Env:
`$SUBMILLI_SERVER_TOKEN_FILE`
-h, --help Print help
Authenticate outbound OAuth MCP servers declared in a blueprint
Usage: submilli server mcp <COMMAND>
Commands:
authenticate Run the OAuth flow for a blueprint's MCP server and store its refresh token.
Re-run to re-authenticate (e.g. after changing scopes) — it overwrites the
existing credential
deauthenticate Remove an MCP server's stored refresh token (blueprint returns to PENDING)
auth-status Show each declared MCP server's authentication state
grants List the MCP OAuth grants the server holds, or delete one
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
Run the OAuth flow for a blueprint's MCP server and store its refresh token. Re-run to
re-authenticate (e.g. after changing scopes) — it overwrites the existing credential
Usage: submilli server mcp authenticate [OPTIONS] <BLUEPRINT> <SERVER>
Arguments:
<BLUEPRINT> Blueprint that declares the MCP server
<SERVER> The MCP server's local name (its key in the `mcp:` block)
Options:
--server <URL> Base URL of the running submilli-server [env: SUBMILLI_SERVER_URL=]
[default: http://127.0.0.1:8128]
--token-file <PATH> File holding the API token to send. Without it the token is read from
`$SUBMILLI_SERVER_TOKEN`; with neither, no token is sent, which only a
server started with `--allow-unauthenticated` accepts. There is no flag
taking the token itself, so it never lands in the process list. Env:
`$SUBMILLI_SERVER_TOKEN_FILE`
-h, --help Print help
Remove an MCP server's stored refresh token (blueprint returns to PENDING)
Usage: submilli server mcp deauthenticate [OPTIONS] <BLUEPRINT> <SERVER>
Arguments:
<BLUEPRINT> Blueprint that declares the MCP server
<SERVER> The MCP server's local name (its key in the `mcp:` block)
Options:
--server <URL> Base URL of the running submilli-server [env: SUBMILLI_SERVER_URL=]
[default: http://127.0.0.1:8128]
--token-file <PATH> File holding the API token to send. Without it the token is read from
`$SUBMILLI_SERVER_TOKEN`; with neither, no token is sent, which only a
server started with `--allow-unauthenticated` accepts. There is no flag
taking the token itself, so it never lands in the process list. Env:
`$SUBMILLI_SERVER_TOKEN_FILE`
-h, --help Print help
Show each declared MCP server's authentication state
Usage: submilli server mcp auth-status [OPTIONS] <BLUEPRINT>
Arguments:
<BLUEPRINT> Blueprint to report on
Options:
--server <URL> Base URL of the running submilli-server [env: SUBMILLI_SERVER_URL=]
[default: http://127.0.0.1:8128]
--token-file <PATH> File holding the API token to send. Without it the token is read from
`$SUBMILLI_SERVER_TOKEN`; with neither, no token is sent, which only a
server started with `--allow-unauthenticated` accepts. There is no flag
taking the token itself, so it never lands in the process list. Env:
`$SUBMILLI_SERVER_TOKEN_FILE`
-h, --help Print help
List the MCP OAuth grants the server holds, or delete one
Usage: submilli server mcp grants <COMMAND>
Commands:
list List the grants, one per blueprint and MCP server
delete Delete a grant, even one whose blueprint no longer declares the server
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
List the grants, one per blueprint and MCP server
Usage: submilli server mcp grants list [OPTIONS]
Options:
--blueprint <BLUEPRINT> Only list this blueprint's grants
--server <URL> Base URL of the running submilli-server [env: SUBMILLI_SERVER_URL=]
[default: http://127.0.0.1:8128]
--token-file <PATH> File holding the API token to send. Without it the token is read from
`$SUBMILLI_SERVER_TOKEN`; with neither, no token is sent, which only
a server started with `--allow-unauthenticated` accepts. There is no
flag taking the token itself, so it never lands in the process list.
Env: `$SUBMILLI_SERVER_TOKEN_FILE`
-h, --help Print help
Delete a grant, even one whose blueprint no longer declares the server
Usage: submilli server mcp grants delete [OPTIONS] <BLUEPRINT> <SERVER>
Arguments:
<BLUEPRINT> Blueprint the grant belongs to
<SERVER> The MCP server's local name (its key in the `mcp:` block)
Options:
--server <URL> Base URL of the running submilli-server [env: SUBMILLI_SERVER_URL=]
[default: http://127.0.0.1:8128]
--token-file <PATH> File holding the API token to send. Without it the token is read from
`$SUBMILLI_SERVER_TOKEN`; with neither, no token is sent, which only a
server started with `--allow-unauthenticated` accepts. There is no flag
taking the token itself, so it never lands in the process list. Env:
`$SUBMILLI_SERVER_TOKEN_FILE`
-h, --help Print help
Run a local playground that serves this project's blueprint and shows every run (macOS and Linux)
Usage: submilli playground [OPTIONS]
submilli playground <COMMAND>
Run `submilli playground` to start and open the browser.
Use the browser to chat and review runs, decision explanations, and comparisons.
Commands:
Start and open the browser:
start Start the playground and open the browser
(default)
open Open the playground in your browser
init-demo Create a demo project with example billing
operations
status Show whether the playground is running
restart Restart the playground and open the browser
stop Stop the playground and finish active runs
Run from the terminal:
chat <MESSAGE> Give an agent a task using your model key or
Claude Code
exec <FILE|--example> Run a program or the demo example
bind Set variables and development secrets for new
runs
session <COMMAND> Start or end a session
sessions List sessions, newest first
cancel <RUN> Cancel an active run
watch Follow session events as JSON lines
Connect a coding assistant:
mcp Serve playground tools to a coding assistant
Advanced inspection and testing:
runs List recorded runs, newest first
show <RUN> Show a run, its calls, and its outcome
explain <RUN.N> Explain why a decision was allowed or refused
compare <RUN-A> <RUN-B> Show which decisions differ between two runs
audit Audit runs since the last Blueprint edit
changes List Blueprint versions and their changes
recheck <RUN> Check recorded decisions against the current
Blueprint
test <RUN> Run again using recorded call responses
rerun <RUN> Run again for real, using current variables
draft-rule <RUN.N> Draft a permission rule for one refused call
clear Delete recorded runs and session events
Run `submilli playground <COMMAND> --help` for arguments and options.
Start options (also available on `start`):
--json Print the ready record as JSON
--no-open Don't open the login link in your browser. A start in a terminal opens
it; one with `--json`, or whose output isn't a terminal, never does
--foreground Serve in this terminal until `submilli playground stop` or a signal,
instead of in the background
--blueprint <PATH> The blueprint to serve. Default: the single file under
`submilli/blueprints/`, or the project's root `blueprint.yaml`
--allow-localhost Let programs reach IPv4 and IPv6 loopback, for an app's local services.
Env: `$SUBMILLI_ALLOW_LOCALHOST` (`1`/`true`/`yes`/`on`), additive
--allow-private Let programs reach RFC1918, CGNAT, and IPv6 ULA private ranges. Env:
`$SUBMILLI_ALLOW_PRIVATE` (`1`/`true`/`yes`/`on`), additive
--allow-ip <IP|CIDR> Let programs reach this address or CIDR range (repeatable). Env:
`$SUBMILLI_ALLOW_IP` (comma-separated), additive
-h, --help Print help
Start the playground in the background, or attach to the running one, print its ready record with a
fresh login link, and open the link in your browser (the default).
Usage: submilli playground start [OPTIONS]
Options:
--json
Print the ready record as JSON
--no-open
Don't open the login link in your browser. A start in a terminal opens it; one with
`--json`, or whose output isn't a terminal, never does
--foreground
Serve in this terminal until `submilli playground stop` or a signal, instead of in the
background
--blueprint <PATH>
The blueprint to serve. Default: the single file under `submilli/blueprints/`, or the
project's root `blueprint.yaml`
--allow-localhost
Let programs reach IPv4 and IPv6 loopback, for an app's local services. Env:
`$SUBMILLI_ALLOW_LOCALHOST` (`1`/`true`/`yes`/`on`), additive
--allow-private
Let programs reach RFC1918, CGNAT, and IPv6 ULA private ranges. Env:
`$SUBMILLI_ALLOW_PRIVATE` (`1`/`true`/`yes`/`on`), additive
--allow-ip <IP|CIDR>
Let programs reach this address or CIDR range (repeatable). Env: `$SUBMILLI_ALLOW_IP`
(comma-separated), additive
-h, --help
Print help (see a summary with '-h')
Print a fresh single-use login link for the running playground, and open it in your browser.
Usage: submilli playground open [OPTIONS] [RUN]
Arguments:
[RUN]
A run to open the page at, or a decision as `<run>.<n>` (for example `12` or `12.3`)
Options:
--json
Print JSON
--no-open
Only print the link. In a terminal it is opened too; with `--json`, or when the output
isn't a terminal, it never is
-h, --help
Print help (see a summary with '-h')
Create a `submilli/` folder with a starter billing package, a blueprint that pins charges to the
signed-in customer, and an example program. Writes nothing outside `submilli/`.
Usage: submilli playground init-demo [OPTIONS]
Options:
--json
Print JSON
-h, --help
Print help (see a summary with '-h')
Report whether the playground is running, where, and with what.
Usage: submilli playground status [OPTIONS]
Options:
--json
Print JSON
-h, --help
Print help (see a summary with '-h')
Stop the running playground and start it again, with its blueprint and egress grants unless given
here, and open a fresh login link. Browser sessions keep their original 12-hour expiry; bound
secrets have to be bound again.
Usage: submilli playground restart [OPTIONS]
Options:
--json
Print the ready record as JSON
--no-open
Don't open the login link in your browser. A start in a terminal opens it; one with
`--json`, or whose output isn't a terminal, never does
--foreground
Serve in this terminal until `submilli playground stop` or a signal, instead of in the
background
--blueprint <PATH>
The blueprint to serve. Default: the single file under `submilli/blueprints/`, or the
project's root `blueprint.yaml`
--allow-localhost
Let programs reach IPv4 and IPv6 loopback, for an app's local services. Env:
`$SUBMILLI_ALLOW_LOCALHOST` (`1`/`true`/`yes`/`on`), additive
--allow-private
Let programs reach RFC1918, CGNAT, and IPv6 ULA private ranges. Env:
`$SUBMILLI_ALLOW_PRIVATE` (`1`/`true`/`yes`/`on`), additive
--allow-ip <IP|CIDR>
Let programs reach this address or CIDR range (repeatable). Env: `$SUBMILLI_ALLOW_IP`
(comma-separated), additive
-h, --help
Print help (see a summary with '-h')
Stop the running playground: drain its runs and end browser sessions.
Usage: submilli playground stop [OPTIONS]
Options:
--json
Print JSON
-h, --help
Print help (see a summary with '-h')
Chat with an agent using your own model key or your own Claude Code, the way a production agent
runs: it uses the playground's tools and prints its answer. Each chat starts a session; send the
next message in it with `--session`. The session stays open until it sits idle past the blueprint's
idle timeout or `session end` ends it. The key (ANTHROPIC_API_KEY, OPENAI_API_KEY, or
GEMINI_API_KEY) comes from the playground's environment, else the project's `.env`, else `submilli
secret put <NAME>`; Claude Code (`--model claude-code:<model>`) needs none. The model comes from
`--model` or SUBMILLI_PLAYGROUND_MODEL=<provider>:<model>. Its runs are labeled `chat`.
Usage: submilli playground chat [OPTIONS] <MESSAGE>
Arguments:
<MESSAGE>
What the agent should do, or, with `--session`, the next message to it
Options:
--session <ID>
Carry on this chat session: the agent sees the conversation so far, under the session's
fixed variables, and answers with the session's own model
--model <PROVIDER:MODEL>
The model for a new session, as `<provider>:<model>`, from a provider whose key the
playground started with, or `claude-code:<model>` to answer with your own Claude Code,
where the model is a full name such as claude-sonnet-5-5, claude-opus-5-5,
claude-fable-5-1, or claude-haiku-5-5. Default: the playground's configured model. A
session carried on keeps its own
--effort <LEVEL>
How hard a new session's model reasons: OpenAI models take low, medium, or high; Claude
Code also takes xhigh and max
[possible values: low, medium, high, xhigh, max]
--max-budget-usd <USD>
The most a new Claude Code session may spend on one message, in US dollars, above 0 and at
most 100. Default: 1.00. On a subscription it measures usage, not billing. Claude Code
checks it between steps, so a message's last step can go a little over
--confirm-billing <BILLING>
Let Claude Code bill what isn't your Claude subscription, such as an API key or an
`ANTHROPIC_BASE_URL` address, in this session: the value the refusal names, such as
`api_key` or `claude.ai via https://proxy.example`
--max-output <TOKENS>
The most tokens one answer of a new session's model may take. Default: 4096
--provider-settings <JSON>
Fields a new session adds to every request to its provider, as a JSON object in the
provider's own API terms, such as `{"temperature": 0.2}`. Fields the playground sets
itself (the model, messages, tools, instructions) are refused
--max-calls-per-answer <N>
The most tool calls run for one answer of the model; the rest are refused to it. Claude
Code counts them across the whole message, and stops at the limit
[default: 16]
--json
Print JSON
-h, --help
Print help (see a summary with '-h')
Run a program in the running playground, labeled `assistant` (or the scaffolded example, labeled
`example`), under the binding or in a started session.
Usage: submilli playground exec [OPTIONS] <FILE|--example>
Arguments:
[FILE]
The program to run
Options:
--example
Run the scaffolded example program instead
--session <ID>
Run in this started session, under its fixed variables
--var <NAME=VALUE>
A variable for this run over the binding (repeatable). In a started session it must match
the session's value
--json
Print JSON
-h, --help
Print help (see a summary with '-h')
Set the variables and harness-secret development values new runs use, or print them. Variables are
kept for the next start; secret values only in the running playground's memory.
Usage: submilli playground bind [OPTIONS] [NAME=VALUE]...
Arguments:
[NAME=VALUE]...
Variables to bind
Options:
--secret <NAME>
A harness secret to bind, its value read from the environment variable of the same name or
the local secret store; never from the command line (repeatable)
--unset <NAME>
Remove a variable or secret from the binding (repeatable)
--clear
Remove everything from the binding first
--json
Print JSON
-h, --help
Print help (see a summary with '-h')
Start a session with its variables fixed, or end one.
Usage: submilli playground session <COMMAND>
Commands:
start Start a session. Variables not given come from the binding; secrets from the binding
end End a session
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help (see a summary with '-h')
Start a session. Variables not given come from the binding; secrets from the binding
Usage: submilli playground session start [OPTIONS]
Options:
--var <NAME=VALUE> A variable for the session (repeatable)
--json Print JSON
-h, --help Print help
End a session
Usage: submilli playground session end [OPTIONS] <ID>
Arguments:
<ID>
Options:
--json Print JSON
-h, --help Print help
List sessions, newest first.
Usage: submilli playground sessions [OPTIONS]
Options:
--limit <LIMIT>
How many sessions to list; tests' and reruns' own sessions come on top, up to as many
[default: 20]
--json
Print JSON
-h, --help
Print help (see a summary with '-h')
Cancel a run in flight.
Usage: submilli playground cancel [OPTIONS] <RUN>
Arguments:
<RUN>
The run id
Options:
--json
Print JSON
-h, --help
Print help (see a summary with '-h')
Follow a session's events as JSON lines until its last run finishes (`--follow`: until the session
ends). Without a session, follows the most recent one. On a session already idle it prints the
events so far and exits at once, so start it after the run it is to follow has started, or pass
`--follow`.
Usage: submilli playground watch [OPTIONS] [SESSION]
Arguments:
[SESSION]
The session to follow
Options:
--follow
Keep following after the session goes idle, until it ends or the playground stops
--json
Accepted for symmetry; `watch` always prints JSON lines
-h, --help
Print help (see a summary with '-h')
Serve the running playground's tools over stdio, for a coding assistant's stand-in subagent to
launch. Uses the binding and the development secrets; its runs are labeled `stand-in`.
Usage: submilli playground mcp
Options:
-h, --help
Print help (see a summary with '-h')
List stored runs, newest first. Works with the playground stopped.
Usage: submilli playground runs [OPTIONS]
Options:
--source <LABEL>
Only runs with this source label (`stand-in`, `app`, `assistant`, ...)
--since <DURATION|RUN>
Only runs that started within this long (`30s`, `10m`, `2h`, `1d`), or after this run id
--session <ID>
Only runs in this session
--limit <LIMIT>
How many runs to list
[default: 20]
--json
Print JSON
-h, --help
Print help (see a summary with '-h')
Show one run: its decisions, calls, and outcome.
Usage: submilli playground show [OPTIONS] <RUN>
Arguments:
<RUN>
The run id
Options:
--include-payloads
Include call request and response bodies, and results and console output in full
--program
Include the program the run ran, as the agent wrote it
--json
Print JSON
-h, --help
Print help (see a summary with '-h')
Explain one decision: the rule that decided it (or the default) and every rule that nearly matched.
Usage: submilli playground explain [OPTIONS] <RUN.N>
Arguments:
<RUN.N>
The decision, as `<run>.<n>` (for example `12.3`)
Options:
--json
Print JSON
-h, --help
Print help (see a summary with '-h')
Compare two runs: only the decisions that changed.
Usage: submilli playground compare [OPTIONS] <RUN-A> <RUN-B>
Arguments:
<RUN-A>
<RUN-B>
Options:
--json
Print JSON
-h, --help
Print help (see a summary with '-h')
Audit the runs since the last blueprint edit.
Usage: submilli playground audit [OPTIONS]
Options:
--default-only
Only calls allowed by the default, which no rule matched
--packages-only
Only calls made by packages
--json
Print JSON
-h, --help
Print help (see a summary with '-h')
List the blueprint versions and what each changed.
Usage: submilli playground changes [OPTIONS]
Options:
--version <N>
Only this version, with its file text
--json
Print JSON
-h, --help
Print help (see a summary with '-h')
After a blueprint edit, see which of a run's decisions would change: re-resolves them under the
blueprint in force. Runs nothing and records nothing.
Usage: submilli playground recheck [OPTIONS] <RUN>
Arguments:
<RUN>
The run id
Options:
--json
Print JSON
-h, --help
Print help (see a summary with '-h')
After a blueprint edit, see whether a recorded program gets through now: runs it again under the
blueprint in force, with its calls answered from the recording. It stops at a call with nothing
recorded.
Usage: submilli playground test [OPTIONS] <RUN>
Arguments:
<RUN>
The run to test
Options:
--reads-live
Let unrecorded reads (`GET`, `HEAD`) go live; anything else still stops the run
--live
Let every unrecorded call go live
--json
Print JSON
-h, --help
Print help (see a summary with '-h')
After a package edit, or to try other variables, run a recorded program again for real under the
current binding, as a new run linked to its source.
Usage: submilli playground rerun [OPTIONS] <RUN>
Arguments:
<RUN>
The run id
Options:
--json
Print JSON
-h, --help
Print help (see a summary with '-h')
Draft a rule that allows exactly one refused call; `--write` puts it in the blueprint file. Works
with the playground stopped.
Usage: submilli playground draft-rule [OPTIONS] <RUN.N>
Arguments:
<RUN.N>
The refused decision, as `<run>.<n>`
Options:
--write
Write the rule into the blueprint file
--name <NAME>
Name the rule, so decisions cite it by name; written as its first key. It must be new to
its caller's block
--json
Print JSON
-h, --help
Print help (see a summary with '-h')
Remove every stored run and its sessions' events, and start a new audit window. Run ids keep
counting, and started sessions stay listed.
Usage: submilli playground clear [OPTIONS]
Options:
--json
Print JSON
-h, --help
Print help (see a summary with '-h')