# The CLI

`thymercli` is Thymer's command-line tool. The same executable runs the MCP server for the browser; see [Connect an AI agent with MCP](connect-an-ai-agent-with-mcp.md). Download it from [thymer.com/mcp](https://thymer.com/mcp). Its `--help` output calls it `thymer`.

The CLI talks to a running server connected to Thymer: either the desktop app's MCP server or `thymercli` itself with the browser connected. Workspace commands need the workspace set to **Read Only** or **Read & Write** in **Settings → MCP (AI Agents)**.

## First steps

```bash
thymercli status
thymercli workspace list
thymercli collection list -w "Docs"
thymercli page list -w "Docs" -c "Docs"
thymercli search "onboarding" -w "Docs"
thymercli page show PAGE_GUID -w "Docs"
```

Create a page and append to it:

```bash
thymercli page create "CLI test" -w "Docs" -c "Docs"
thymercli page add PAGE_GUID "A note from the terminal." -w "Docs"
```

`page add` appends Markdown and also reads it from standard input, so `cat notes.md | thymercli page add PAGE_GUID` works.

## Options

| Option | Meaning |
| --- | --- |
| `-w`, `--workspace` | Workspace name or guid |
| `-c`, `--collection` | Collection name or guid |
| `-p`, `--port` | Server port, default 13100 |
| `--json` | JSON output, for scripts |
| `-q`, `--quiet`, `--no-color`, `-v` | Less decoration, no color, more detail |

`use workspace NAME` and `use collection NAME` remember a default for the interactive session; `context` shows it and `context clear` forgets it. In scripts, pass `-w` and `-c` every time.

## Commands

| Command | Does |
| --- | --- |
| `thymercli` | Start the MCP server and an interactive prompt |
| `mcp --no-repl` | Start the server only |
| `stdio` | Proxy a stdio MCP client to the running server |
| `status`, `version` | Server status, CLI version |
| `workspace list`, `workspace show NAME` | Workspaces, with their users |
| `collection list`, `collection show NAME` | Collections, with views and properties |
| `collection create NAME`, `collection trash NAME` | Make or trash a collection |
| `collection navigate NAME --view VIEW` | Open it in the app |
| `search QUERY --limit 50` | Search, with the full [query syntax](../search-and-navigation/search.md) |
| `page list`, `page show GUID` | Pages in a collection, one page as Markdown |
| `page create TITLE` | New page |
| `page add GUID [markdown]` | Append Markdown, also from stdin |
| `page insert GUID --type task --content "Follow up"` | Insert one line; `--after` and `--parent` place it |
| `page move GUID... --to COLLECTION` | Move pages |
| `page navigate GUID` | Open it in the app |
| `page trash GUID`, `page untrash GUID` | Trash and restore |
| `line edit GUID --content "New text"` | Change a line |
| `line move GUID --after GUID` | Move a line; `--parent` changes its parent |
| `line flag GUID FLAG`, `line done GUID`, `line delete GUID` | Flag, complete or delete a task or line |
| `property list` | A collection's properties |
| `property get GUID [name]` | A page's values |
| `property set GUID Status=Done Owner=Ada` | Set values |
| `journal [date]` | Show a Journal page |
| `journal add [date] MARKDOWN` | Append to it |
| `journal navigate [date]` | Open it in the app |
| `plugin list`, `plugin show NAME` | Plugins, with code, CSS and configuration |
| `plugin update code NAME --file plugin.js` | Replace a plugin's code; also `config` and `css` |
| `theme list`, `theme get`, `theme set NAME` | Themes |
| `mdmirror PATH` | One-way Markdown export to a folder; `--markdown-mirror-interval 60` repeats it |
| `run 'ls /thymer'` | Run a shell command on the workspace's virtual filesystem |
| `export decrypt --in backup.zip --out plain.zip` | Decrypt a full export; `export encrypt` does the reverse |

Journal dates are `YYYY-MM-DD`. Lines are addressed by guid; `page show` and `search` print them. Every command has `--help`.