The command line guide

Overview

Sill is a set of small programs called cores, one per area, behind one local gateway. You only ever type wros. The interface commands live under wros sill, and sill is an alias for that.

you ── wros task add … ──▶ gateway (127.0.0.1) ──▶ tasks core ──▶ encrypted local database
                                  │                 email, calendar, contacts, codes, media,
                                  │                 pdf, ai, matrix, sms cores
                                  └─ never routes secrets: the connectors core is the only
                                     one that holds passwords and tokens

Each area is a component you can install or leave out. Run a command of a component that is not installed and you get a clear error naming it and the fix. If a core crashes, the supervisor restarts it with a back-off.

Five minutes

$ wros install -d      # choose what to install (-m minimal, -d recommended, -c a,b exactly these)
$ wros up              # start the core in the background (safe to repeat)
$ wros status          # what is running, which accounts are connected
$ wros account connect gmail --email you@gmail.com
$ wros email list --limit 5
$ wros task add "buy milk" --due fri
$ wros help task      # usage of every task command

Not installed yet? Start with the install guide.

Components

wros components lists them. Installing is additive; features that need two components say which one is missing.

Running a command

A command is words and options. Quote anything with spaces. Every command has the shape wros <domain> <action> [arguments] [options].

$ wros task add "buy milk" --due fri --priority important
$ wros email search "is:unread from:alice"
$ wros event add "Standup" --start "fri 09:00"
$ wros contact add "Ada Lovelace" --email ada@example.com

Options every command accepts: --json, --text, --yes, --standalone (ignore a running core), --up (start the core first), --level (cap this call's safety level), --client (the name recorded in the audit log).

Getting help

$ wros help                 # the command list, grouped by domain
$ wros help task            # every task command
$ wros help task add        # one command (same as: wros task add --help)
$ wros commands --json     # every command with a JSON Schema
$ wros schema task.add     # the schema of one command

Ids, dates and paths

• Ids: tables print the first 8 characters. Anywhere an id is expected, any unique prefix of 4 or more characters works.
• Dates: 2026-10-09, today, tomorrow, fri, +3d. Date-times: "fri 14:30", "2026-10-09 09:00" (local time).
• Paths: relative paths are relative to where you are, not to the background core.
• Structured input: wros call <command> --args '<json>', or --args - to read JSON from standard input. It avoids shell quoting for multi-line mail bodies.

Output & exit codes

On a terminal you get tables. Piped, or with --json, you get one JSON envelope. --text forces tables.

$ wros task list
ID        TITLE             PRIORITY   DUE         PIN  REPEAT
--------  ----------------  ---------  ----------  ---  ------
c364b634  buy milk          important  2026-10-16  no   -
(1 rows)

$ wros task list --json
{"command":"task.list","data":[…],"level":"read","ok":true}

Every failure prints error[WROS-Exxx]: <cause> and, when one exists, fix: <command to paste>.

Safety

Every command has a level: read (looks only), write (changes local data), ai (calls an AI provider), send (sends something to other people), destructive (removes for good).

• A person at a terminal gets every level. A script, a pipe or an agent gets read, write and ai.
• Widen or narrow with SILL_LEVEL, with ~/.sill/cli-policy.json, or per call with --level. A call can lower its own level, never raise the session's.
• send and destructive commands always need --yes, even when permitted.
• Every call is appended to ~/.sill/logs/cli-audit.jsonl.
• Secrets are never shown or taken on a command line. No command prints a password, token or API key, and none accepts one as an argument.

You can also see and switch every outside connection the cores make:

$ wros permissions list
$ wros permissions disable <id>

Examples

The full argument list of all commands is in the reference that ships with wros (wros help <domain>).

Run the core

wros up is a detached user process: no administrator rights, no OS service. It takes an instance lock, restarts crashed cores, and listens only on 127.0.0.1 with a random token.

Scripts & AI agents

Piped output is JSON and exit codes are stable, so scripts can rely on both. For AI tools, wros mcp is an MCP server with one tool per command.

$ wros up
$ claude mcp add sill -- wros mcp

• An agent session defaults to read, write and ai. For a read-only assistant, start it with SILL_LEVEL=read.
• Sending mail or deleting needs your permission and confirm: true (--yes in a shell). Agents should never add it on their own.
• An agent cannot read or change passwords, OAuth secrets, tokens or API keys, and cannot add an IMAP account.
• wros events streams changes (email:new, contacts:changed…) as JSON lines.

Troubleshooting

"the tasks component is not installed" (WROS-E317)

Run the fix it prints: wros install -c tasks.

"not answering" (WROS-E319)

A core has crashed. The supervisor restarts it by itself; check wros status and wros logs. After five crashes in ten minutes it gives up, and crash reports are kept under ~/.sill/logs/crashes.

Exit code 4 or WROS-E513

The command sends or deletes something. Check it, then repeat with --yes.

Not in the terminal yet

Matrix / WhatsApp, adding a password (IMAP) account, and the PDF signature editor are app-only for now.