alforria

CLI reference

Commands, flags, and common invocations for the alforria binary.

Run alforria with no subcommand to start the terminal UI. Every command accepts --help; the installed binary is authoritative for the exact option list.

alforria --help
alforria run --help
alforria serve --help

Global options

Option Effect
-v, --version Print the version
--print-logs Print logs to stderr. Only serve prints logs today
--log-level <level> Set the log level: DEBUG, INFO, WARN, ERROR
--pure Reserved for running without external plugins. There is no plugin runtime yet, so it only changes the debug info output
-m, --model <provider/model> Select a model
-c, --continue Continue the latest session
-s, --session <id> Continue a specific session
--fork Fork when continuing
--agent <name> Select an agent
--prompt <text> Start with a prompt
--auto Auto-approve permissions that are not explicitly denied (dangerous)
--port <port> Port for the local server. The default, 0, tries 4096 first, then a random free port
--hostname <host> Hostname for the local server, default 127.0.0.1
--mdns Defaults the hostname to 0.0.0.0 and accepts the --mdns-domain name as a Host. It does not advertise the service yet
--mdns-domain <domain> Host name accepted with --mdns, default opencode.local
--cors <origin> Additional allowed CORS origin, repeatable

alforria <path> starts the TUI in another directory.

Plain alforria runs the server in process and opens no port. Passing --port, --hostname, or --mdns makes it start a real HTTP listener for the TUI instead.

Only serve generates a password. The listeners started by web, acp, run without --attach, and plain alforria with those flags are unauthenticated unless OPENCODE_SERVER_PASSWORD is set.

Commands

Command Purpose
run Run a message without the full TUI
serve Start a headless HTTP/SSE server
web Start the server and open the web client
attach Drive a running server from the TUI
acp Start an Agent Client Protocol server
providers (auth) List, log in to, and log out of providers
models List models, optionally for one provider
agent List agents (create is not available yet)
session List and delete sessions
mcp Manage MCP servers and their auth
stats Show token usage and cost statistics
export / import Move session data as JSON
libertai Show LibertAI plan and usage
pr Fetch and check out a GitHub PR, then run alforria
generate Print the v1 OpenAPI document with code samples
db Print the database path or run SQL
debug Inspect config, paths, agents, snapshots, and tooling

run

alforria run "explain the failure in the latest test log"
alforria run --format json "list the top-level directories"
alforria run -m libertai/<model-id> "review the diff"
alforria run --attach http://localhost:4096 "continue there"
Option Effect
--command <command> Run a command, using the message as arguments
-c, --continue Continue the latest session
-s, --session <id> Continue a specific session
--fork Fork before continuing
--share Share the session
-m, --model <provider/model> Select a model
--agent <name> Select an agent
--format <default|json> Formatted output or raw JSON events
-f, --file <path> Attach one or more files
--title <title> Set the session title
--attach <url> Use a running server
-p, --password <password> Basic auth password for the server
-u, --username <username> Basic auth username
--dir <dir> Directory to run in, or a remote path when attaching
--port <port> Port for the temporary local server. The default, 0, tries 4096 first, then a random free port
--variant <variant> Provider-specific reasoning effort
--thinking Show thinking blocks
--auto Auto-approve permissions (dangerous)

Without --attach, run starts a server on 127.0.0.1 for the length of the run and talks to it over HTTP. It does not generate a password, so set OPENCODE_SERVER_PASSWORD if other local users share the machine.

serve and web

alforria serve --port 4096
alforria serve --hostname 0.0.0.0 --port 4096
alforria web
alforria web --port 4096

serve and web share the network options in the global table. web opens the browser after the server starts.

Only serve generates a password when OPENCODE_SERVER_PASSWORD is not set. web prints OPENCODE_SERVER_PASSWORD is not set; server is unsecured and runs without authentication. Set the variable before alforria web to protect it. See Server and API for authentication and endpoint details.

attach

alforria attach http://localhost:4096
alforria attach http://workstation:4096 -u alforria -p "$SECRET"

Attach options include --dir, -c, -s, --fork, and the basic auth flags. The remote server must already be running. --mini is not available yet: it prints a warning and starts the full TUI.

providers and models

alforria auth list
alforria auth login
alforria auth login -p libertai
alforria auth logout <provider>
alforria models
alforria models libertai
alforria models --verbose
alforria models --refresh

providers login accepts -p, --provider to skip selection and -m, --method to skip the method menu. auth is an alias for providers.

agent

alforria agent list

agent list shows the resolved agents. Agents are discovered from agent/**/*.md and agents/**/*.md in the global config directory and in .opencode directories. See Configuration for the file format.

agent create is not available yet. It requires --path, --description, --mode, and --permissions, then fails with no language model available because agent generation is not wired up. Write the Markdown file by hand instead.

session

alforria session list
alforria session list -n 20 --format json
alforria session delete <session-id>

mcp

alforria mcp list
alforria mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /tmp
alforria mcp add remote --url https://example.com/mcp --header "Authorization=Bearer $TOKEN"
alforria mcp auth <name>
alforria mcp logout <name>

Local servers take a command after -- and --env KEY=VALUE. Remote servers take --url and repeatable --header KEY=VALUE pairs.

stats, export, and import

alforria stats
alforria stats --days 30 --models --tools 10
alforria stats --project ""
alforria export <session-id> > session.json
alforria export <session-id> --sanitize > session-redacted.json
alforria import session.json
alforria import https://<host>/share/<slug>

export --sanitize redacts sensitive transcript and file data. Plain export does not. import takes a local JSON file or a share link of the form https://<host>/share/<slug>. Other URLs are rejected.

LibertAI

alforria libertai usage
alforria libertai usage --json

Shows plan allowance windows and prepaid credits for the signed-in LibertAI account.

ACP

alforria acp

Starts an Agent Client Protocol server over stdio for compatible editors. It also starts a local HTTP server using the network options, which does not generate a password. --cwd is accepted but not used yet.

Database and diagnostics

alforria db path
alforria db "select count(*) from session" --format json
alforria debug paths
alforria debug config
alforria debug info
alforria debug agent <name>
alforria debug startup

debug config prints the resolved configuration after merging every source. debug paths prints the data, config, cache, and state directories. debug agent <name> prints the resolved agent. Running a tool with --tool is not supported yet.

Scripted use

For scripts, prefer run --format json and the HTTP API rather than scraping formatted TUI output. The server exposes the same session engine, and its OpenAPI documents describe every route. See Server and API.