# 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.