Commands

Shoal is a coding agent that runs on your own hardware. It manages the inference server itself, keeps history stable for the server's prefix cache, asks before writes and shell commands, and delegates subtasks to fresh-context sub-agents. Cloud APIs are optional, never required. Install once: shoal setup. Save a default model: shoal config set model <name>. After that, a bare shoal in any terminal is enough. Server lifecycle: shoal up, shoal down, shoal doctor, shoal models. Docks (where models tie up): - mlx: Apple Silicon via mlx_lm.server (macOS only) - llamacpp: NVIDIA CUDA / Metal via llama-server (all platforms) - remote: an existing OpenAI-compatible endpoint

config manages the user-wide defaults so shoal runs without flags. shoal config show the current defaults shoal config set model <name> set the default model shoal config unset model clear a default Keys: model, dock (mlx, llamacpp, remote), endpoint. Precedence at launch: CLI flag, then the project's .shoal/config.json, then these defaults.

desktop runs the engine and opens the Shoal web client in an app-mode window on a loopback port. Closing the window exits Shoal; the inference server follows the usual ownership rules (a server started by shoal up persists, a session-owned one stops).

Detect the host platform, verify the dependencies shoal needs (including the llama-server security floor), and report which inference servers are answering locally.

Stop every shoal-managed inference server and clear stale pid records. A server shoal did not start is reported but left running.

exec runs one prompt on this machine and exits. There is no terminal, nothing listens on a socket, and no ops are read after launch: stdin is at most the prompt. The prompt comes from the argument, from --file, or from stdin, and exactly one of the three. With --workflow the same text becomes the workflow's argument instead. Output modes: text the final assistant text on stdout, notices on stderr json one result document: final text, stop reason, spend, files touched, and every action the ladder refused stream every seam event as JSON lines on stdout, as it happens. This is the mode to script against: the vocabulary is the engine's own protocol, not a second schema Exit codes: 0 the turn completed and nothing was refused 1 the flags or the prompt could not be read 2 the engine did not start 3 the turn ended in an error 4 the turn spent its whole tool call budget 5 the turn finished and the ladder refused at least one call 6 the run was interrupted 7 the input gate answered the prompt without starting a turn Approvals cannot ask anybody here, so they resolve from a rung of the autonomy ladder. The rungs are named after Shoal's own tool classes: read runs from the read rung reads a file or searches the tree delegate runs from the read rung hands work to a sub-agent, whose own calls come back through this same table plan runs from the write rung accepts a decomposition plan write runs from the write rung writes to a file exec runs from the exec rung runs a shell command hook runs from --unsafe-approve-all calls an outside process a hook started tool runs from --unsafe-approve-all carries no classification, so nothing here knows what it does The floor is read, which is the default. A write-classified call at the floor is refused and reported, never dropped in silence. Whether a call needs approving at all is the engine's own decision (internal/ permissions), the same one every other client asks, so a shell command Shoal already treats as read-only runs at the floor too.

Show what is on disk, the model registry with per-dock identifiers, and a hardware-aware recommendation. A model already on disk that fits the memory budget is recommended over a registry download. The sizing is a heuristic (weights against a memory budget with KV headroom); any GGUF path or MLX id outside the registry still works with --model.

proto runs the engine as a child process for GUI clients: protocol events stream out on stdout, one JSON object per line, and ops arrive on stdin the same way. stdout is pure protocol; startup prints and diagnostics go to stderr. Closing stdin shuts the engine down cleanly. Approvals assume an interactive approver on the other end: tool calls that need approval emit approval_requested events and wait for a resolve_approval op. Pass --auto-approve to skip approvals entirely.

secret manages the values a hook needs to authenticate, kept outside every project and readable only by you. shoal secret set <name> store a value, read from a prompt or stdin shoal secret list list names and fingerprints, never values shoal secret rm <name> remove one Reference a secret from a hook's env in hooks.json as ${secret:NAME}. It resolves when the hook process is spawned, into that process's environment, and never into a prompt, a tool result, or a stored session. A value that comes back out in a hook's output is replaced with [redacted:NAME] before it reaches the model.

setup installs the running binary as a per-user program: - copies it to the user programs directory - puts shoal on PATH, so any new terminal runs it by name - registers it with the OS (Start Menu, Apps & features on Windows) Re-running setup from a newer binary upgrades the install in place. --uninstall reverses everything; session data and config are kept. When no default model is saved yet, setup asks for one as part of installing, so a bare shoal starts on every surface afterwards. The same default can always be set or changed by hand: shoal config set model <name>

Start the inference server detached, so it outlives this command. The model loads once; later shoal runs find the server healthy on the port and use it instead of spawning their own. Stop it with shoal down. The server binds to 127.0.0.1 only, never exposed to the network.