henning
844d2e716f
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.
69 lines
2.2 KiB
Markdown
69 lines
2.2 KiB
Markdown
# 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.
|