Manual

Shoal Manual

Learn the Shoal language, run the interactive shell, compose typed data, manage tools with reef, and connect agents through the structured kernel protocol.

For: Users, operators, and agent authors

Welcome to the complete guide to Shoal. Start with the quickstart if you want a working prompt in minutes, or use the language and systems guides as a reference while you build.

Shoal is an early preview. The docs distinguish shipped behavior from design direction so you can experiment without mistaking an aspiration for a guarantee.

Browse the collection

Books and chapters

Book 01

Start here

Build Shoal, learn its mental model, and get comfortable at the prompt.

3 chapters

01 QuickstartBuild Shoal, enter the shell, run a first structured query, and write a script without importing habits that do not apply. 02 The command/expression modelUnderstand how Shoal decides what a line means, where outcomes become errors, and how typed values replace text pipelines. 04 Migrating from traditional shellsTranslate Bash, zsh, fish, and Nushell habits into Shoal's command/expression modes, typed values, outcomes, feeds, scopes, and structured workflows.

Book 02

Language

Syntax, values, functions, control flow, outcomes, collections, and data methods.

5 chapters

06 Syntax and literalsA grammar-oriented tour of statements, command words, strings, numbers, units, collections, operators, chaining, and continuation. 07 Values, types, and methodsShoal's runtime data model, access rules, equality, arithmetic, conversion boundaries, secrets, and the core collection method vocabulary. 08 Functions, control flow, and modulesDeclare bindings and typed functions, use command-call syntax, branch and match, scope state, build modules, and choose source versus script execution. 09 Outcomes and errorsHandle command status without losing output, understand statement versus value position, recover typed errors, and propagate failures intentionally. 10 Collections, tables, and data namespacesQuery records and tables, choose eager or streaming transforms, parse common formats, call HTTP, use math, and inspect host/config data.

Book 03

Shell & tools

External programs, live data, files, jobs, configuration, prompts, and tool resolution.

9 chapters

03 Command-line interfaceEvery Shoal entry point: interactive use, one-liners, scripts, stdin, formatting, diagnostics, completions, prompt tools, LSP, and MCP. 05 Interactive shellUse the local REPL confidently: editing, completion, transcript values, jobs, history, paging, init files, and recovery. 11 External commands and data exchangeRun raw and adapted programs, understand PTY versus capture, serialize stdin with feed, redirect output, and embed interpreter source safely. 12 Streams and channelsBuild bounded live dataflows from timers, filesystem events, tailed files, and named channels—with explicit sinks and honest overflow behavior. 13 Filesystem, jobs, history, and undoUse structured filesystem builtins, manage local tasks and process groups, inspect the journal, and understand exactly which mutations can be reversed. 14 RecipesPractical Shoal patterns for files, structured data, external commands, HTTP, streams, modules, Reef, journaling, and agents. 15 Configuration and promptLayer Shoal configuration safely, tune history and rendering, and build a fast structured prompt. 16 Command adaptersUnderstand Shoal's typed command adapters, structured output contracts, bundled catalog, and extension format. 18 Reef tool resolutionMake tool selection explicit with scoped manifests, content-hashed locks, providers, synthesized PATH views, and script runners.

Book 04

Agents & protocol

Structured sessions, the kernel contract, MCP tools and resources, agent workflows, and trust boundaries.

7 chapters

19 Agents, kernel, and MCPRun Shoal as a long-lived structured execution service for agents, clients, and interactive terminal programs. 20 MCP tool referenceExact schemas, defaults, return shapes, and failure behavior for all thirteen Shoal MCP tools. 21 MCP resources and eventsAddressable Shoal values, session views, task and PTY resources, event cursors, replay, and subscription behavior. 22 Kernel JSON-RPC protocolThe raw newline-framed Shoal kernel API: attachment, execution, values, tasks, plans, PTYs, events, wire types, and errors. 23 Agent and MCP workflowsReliable patterns for structured execution, planning and approval, drill-down retrieval, background tasks, events, PTYs, and reconnect recovery. 24 Security and trust boundariesThreat model, socket and token authentication, Leash policy, sandbox enforcement, secret handling, isolation gaps, and safe deployment guidance. 25 Companion CLI referenceInstall and use shoal-kernel, shoal-mcp, shoal-lsp, shoal-token, shoal-secret, shoal-history, shoal-doctor, and sandbox helpers.

Book 05

Project

An honest implementation ledger, current limits, and the roadmap from preview to a dependable daily shell.

3 chapters

26 Current status and limitsA dated, source-verified implementation matrix and an honest account of Shoal's security, protocol, language, platform, and operational limitations. 27 RoadmapPriority-ordered work from trusted-local preview to a hardened structured shell and agent runtime, with concrete acceptance criteria. 28 TroubleshootingDiagnose installation, parsing, command resolution, adapters, Reef, configuration, journals, kernel/MCP, tokens, tasks, events, PTYs, and platform-specific failures.

Book 06

Reference

Dense grammar, builtin, namespace, value-method, and companion-command references for daily use.

6 chapters

17 Keybinding referenceConfigure Emacs or Vi editing, parse key chords, map every supported action, and diagnose terminal/keybinding conflicts. 29 Reference inventory and glossaryThe map of Shoal documentation, binaries, files, environment variables, adapter catalog, protocol surfaces, and shared terminology. 30 Grammar, operators, patterns, and interpolationA parser-level reference for Shoal source: dispatch modes, complete expression precedence, statement forms, command arguments, patterns, literals, and continuation. 31 Builtin command referenceEvery canonical Shoal builtin command head, with accepted arguments, options, result shape, examples, effects, and important errors. 32 Namespace referenceEvery member of Shoal's json, yaml, toml, csv, math, http, os, and config namespaces, plus environment and secret access. 33 Value types and every methodThe complete runtime value and method surface, organized by receiver type with signatures, return shapes, consumption rules, and errors.