Build

bazel build //:sl

The binary is bazel-bin/app/sl. Add it to your PATH if needed:

mkdir -p "$HOME/bin"
cp bazel-bin/app/sl "$HOME/bin/sl"

Prompts and input

Use one instruction source: --prompt or --prompt_file. Piped stdin is optional context, not a replacement for the instruction source.

sl --prompt "Review the authentication flow"
sl --prompt_file task.md --session incident
cat build.log | sl --prompt "Explain this failure"
sl --db /tmp/project.db --prompt "Inspect the database"
sl --ephemeral --prompt "Try this without changing the ledger"

Live prompts need model configuration and credentials. Use the same setup described in the walkthrough.

System prompt override

Override only the built-in system_prompt.md content for one process. Tool instructions, skills, AGENTS.md, conversation history guidance, and follow-up behavior remain enabled:

sl --system_prompt "You are a concise release-note assistant." --prompt "Summarize these changes"
sl --system_prompt_file ./release-system-prompt.md --prompt "Summarize these changes"

Use at most one of --system_prompt and --system_prompt_file. The override is not persisted.

Database selection

Without --db or --ephemeral, sl uses the configured database or slop.db. --db and --ephemeral are mutually exclusive.

Keep the database and SQLite sidecar files outside the repository, or ignore them in Git. The ledger can contain sensitive prompt and tool data.

JSON and schema output

Every JSON-producing command must explicitly use --json. --schema requires --json and emits the validated structured value directly.

sl --prompt "Extract the issue" --json
sl --prompt "Extract the issue" --json --schema issue.schema.json
sl context show --json
sl session list --json

The flag names differ from std_slop batch mode:

For std_slop batch output fields and the supported schema subset, see interactive and batch usage. Structured batch output cannot be combined with --output=json.

State subcommands

Database and agent state are available through shell-friendly subcommands. Slash commands are available only in the interactive std_slop TUI.

sl context show
sl context set --retain_groups=2 --watermark_tokens=350000
sl session list
sl message list
sl scratchpad show
sl skill list
sl stats
sl tool list
sl mcp list

These examples cover context, sessions, messages, scratchpad state, skills, statistics, tools, and registered MCP endpoints. The outbound client supports HTTP servers and modern-only stdio subprocesses.

MCP commands and configuration

sl mcp uses the same HTTP/stdio registry and command handler as std_slop mcp. These commands manage registrations and token files, not the agent session database. Registration does not start a configured process.

The command names are oauth-login and oauth-refresh, not login and refresh. Options use separate arguments, such as --auth bearer, not --auth=bearer.

Register a server

# No authentication (--auth none is the default).
sl mcp add public --url https://example.com/mcp

# Static bearer token; do not paste secrets into shared shell history.
sl mcp add private --url https://example.com/mcp \
  --auth bearer --token "$TOKEN"

# OAuth endpoint discovery; the provider must supply a registered client ID.
sl mcp add work --url https://example.com/mcp \
  --auth oauth --client-id "$CLIENT_ID" --scope read --scope write

# Local stdio server; command and argv are passed without a shell.
sl mcp add local-files --transport stdio \
  --command /absolute/path/to/mcp-server \
  --args-json '["--root", "/work/project"]'

Bundled local workspace tools

The repository includes a local stdio server that uses its launch directory as the default workspace and discovers linked Git worktrees dynamically. Build and register it with no extra arguments or saved workspace path:

bazel build //mcp/local_tools:local_tools_server
sl mcp add local-tools --transport stdio \
  --command /absolute/path/to/bazel-bin/mcp/local_tools/local_tools_server

The server provides workspace listing/info, file read/list/grep/write/edit, and shell tools, but no dedicated Git tools. File paths are relative to the selected workspace; shell starts there but is not sandboxed. See the MCP user guide for limits and the full tool contract.

When std_slop runs in mail mode, all imported MCP calls—including read-only hints—are blocked unless the host is on a slop/staging/* branch. This branch gate does not sandbox an allowed MCP call or shell command.

For HTTP servers, --auth accepts none, bearer, or oauth. Bearer mode requires --token; OAuth mode requires --client-id. --scope may be repeated. OAuth scopes are provider-specific: select the scopes required by the tools you plan to use; std_slop does not infer them. A login can succeed while later tool calls fail for insufficient scope. After changing scopes, run std_slop mcp oauth-login NAME again. --token-path PATH overrides the default token location. Server names use letters, digits, hyphens, or underscores.

SondaHub provides a public endpoint and an OAuth endpoint. The public endpoint needs no OAuth. For OAuth, request mcp:read for read tools and mcp:write for write tools:

std_slop mcp add sondahub-public --url https://api.sondahub.com/mcp
std_slop mcp add sondahub --url https://api.sondahub.com/mcp/secure \
  --auth oauth --client-id sonda --scope mcp:read --scope mcp:write
std_slop mcp oauth-login sondahub

For stdio servers, --args-json is optional and defaults to an empty array; when supplied, it must be a JSON array of strings. Arguments are literal argv values; no shell is started and $VAR or ~ is not expanded. The executable inherits the agent's environment, working directory, user permissions, and local file access. Configure only trusted executables. Stdio supports modern MCP 2026-07-28 only and has no HTTP/OAuth authentication.

If OAuth discovery is unavailable, supply both HTTPS endpoints and the issuer:

sl mcp add work --url https://example.com/mcp \
  --auth oauth --client-id "$CLIENT_ID" \
  --authorization-endpoint https://auth.example.com/authorize \
  --token-endpoint https://auth.example.com/token \
  --issuer https://auth.example.com

Files and output

• Registrations are stored in ~/.config/slop/mcp.ini, in [server.NAME] sections. Repeating add replaces an entry; omitted fields are not merged with the old entry.
• Tokens default to ~/.config/slop/mcp/tokens/NAME.json and are saved with mode 0600. Tokens are not stored in the registry or SQLite. Client secrets are not saved.
• MCP management uses the default registry path. Agent flags such as --config, --db, --ephemeral, and --session do not select a different MCP registry or make registration changes temporary.
• sl mcp list --json returns the command's text under result.output, not a structured array of servers.
• To disable a server without removing it, set enabled = false in its registry section. There is no enable/disable CLI command.

For example:

sl mcp list --json
sl mcp oauth-refresh work
sl mcp logout work
sl mcp remove work

OAuth login needs interactive input. sl currently buffers the shared handler's output, so its URL and prompt are not displayed before the callback read. Use std_slop mcp oauth-login work for browser-paste login. If the provider requires a client secret, set SLOP_MCP_CLIENT_SECRET in the environment through a secure prompt; OAuth commands do not accept secret values as arguments.

For registry examples, process lifetime, discovery requirements, and the full login flow, see the MCP integration guide. The runtime starts enabled stdio children at startup; each sl prompt invocation has its own processes.

Related guides

• Sessions: session state and ownership.
• Context management: retained history and token watermarks.
• Personas and skills: shared instructions and modular skills.
• Mail workflows: staging, review, approval, and finalization protections.
• MCP agent integration: external HTTP tools and authorization.
• Agent database and schema: the runtime data model.