Add outline-cli: minimal CLI for search and document retrieval

Adds a command-line client in cli/ as its own Cargo workspace, depending on the outline library via a path dependency. Covers exactly the requested scope: login (stores the API key in the system keyring via the Secret Service D-Bus protocol, verified against auth.info() before storing), search (full-text), and get (fetch a document, render its markdown to a self-contained HTML page, open it in the default browser). Verified end-to-end against a real Outline instance and the local gnome-keyring: login stores and search/get retrieve the token purely from the keyring and saved config, with no environment variables set.
2026-07-30 15:15:56 +02:00
parent a32a437557
commit 844d2e716f
16 changed files with 3667 additions and 0 deletions
@@ -0,0 +1,68 @@
+# outline-cli
+
+A command-line client for [Outline](https://www.getoutline.com), built on the
+[`outline`](../README.md) library. Search documents and open them locally,
+rendered from markdown to HTML, in your default browser.
+
+This is a separate Cargo workspace from the library (its own `Cargo.lock`),
+depending on it via a path dependency.
+
+## Install / build
+
+```sh
+cargo build --release
+# binary at target/release/outline
+```
+
+## Usage
+
+```sh
+# Store an API key (created under Outline Settings → API & Apps) in the
+# system keyring (GNOME Keyring / KWallet via the Secret Service D-Bus API).
+outline login
+
+# Full-text search
+outline search "onboarding"
+
+# Fetch a document by id, urlId, or a pasted document URL — renders its
+# markdown to HTML and opens it in your default browser.
+outline get hDYep1TPAM
+```
+
+For a self-hosted instance:
+
+```sh
+outline --base-url https://wiki.example.com login
+```
+
+The instance URL is remembered (in `~/.config/outline-cli/config.toml`) after
+`login`, so it doesn't need to be repeated on every command.
+
+## Configuration
+
+| Source | Purpose | Precedence |
+|---|---|---|
+| `--base-url` / `$OUTLINE_URL` | Outline instance | 1 (highest) |
+| `~/.config/outline-cli/config.toml` | saved instance URL (written by `login`) | 2 |
+| Outline Cloud default | fallback | 3 |
+| `--api-key` / `$OUTLINE_API_KEY` | API key | 1 |
+| system keyring (Secret Service) | saved API key, per instance (written by `login`) | 2 |
+
+The API key is **never** written to the config file — it lives exclusively in
+the system keyring, looked up by the resolved instance URL.
+
+Rendered documents are cached in `~/.cache/outline-cli/` (mode `0600`, not
+`/tmp`, since documents may be confidential).
+
+## Requirements
+
+A running [Secret Service](https://specifications.freedesktop.org/secret-service/latest/)
+provider (GNOME Keyring or KWallet) is required for `outline login` / for
+`search`/`get` to find a stored key. On headless systems, skip the keyring
+entirely and pass `--api-key` or set `$OUTLINE_API_KEY` instead.
+
+## Status
+
+Minimal first version: `login`, `search`, `get`. No `logout`, no rate-limit
+retries, no export/attachment handling — see the library's own README for
+the broader API coverage roadmap.