Metadata-Version: 2.4
Name: outline-kb-cli
Version: 0.2.0
Summary: A Python client and CLI for Outline knowledge bases
Author-email: VisualDust <gavin@gong.host>
Maintainer-email: VisualDust <gavin@gong.host>
License: MIT
Project-URL: Homepage, https://github.com/visualdust/outline-skills
Project-URL: Repository, https://github.com/visualdust/outline-skills
Project-URL: Issues, https://github.com/visualdust/outline-skills/issues
Project-URL: Documentation, https://github.com/visualdust/outline-skills#readme
Keywords: outline,knowledge-base,documentation,wiki,collaboration,cli,api-client
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Office/Business
Classifier: Topic :: Documentation
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: markdown-it-py>=3.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pre-commit>=3.7; extra == "dev"
Requires-Dist: ruff>=0.11.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Dynamic: license-file

# Outline Skills

An [Agent Skills](https://agentskills.io/specification) package for operating [Outline](https://www.getoutline.com/) knowledge bases through `outline-cli`.

Manage documents, collections, search, comments, attachments, users/groups, sharing, and related workflows. Publish local Markdown with uploaded assets, and create rich-text document references using Outline's mention syntax.

**One skill directory, shared across compatible agents.** No separate skill format or OpenAI-specific manifest is required. The skill supplies instructions; the Python CLI supplies the API client.

## Install

### 1. Install the CLI

```bash
pip install outline-kb-cli
```

The output controls below require CLI **0.2.0** or the current source checkout. Until that version is published, install from a checkout with `pip install -e .` in the repository root.

### 2. Install the skill

Use the cross-agent [skills installer](https://github.com/vercel-labs/skills) (requires Node.js/npm):

```bash
npx skills add visualdust/outline-skills --skill outline-skills
```

Choose your agent in the installer, or specify one explicitly:

```bash
npx skills add visualdust/outline-skills --skill outline-skills -a codex
npx skills add visualdust/outline-skills --skill outline-skills -a claude-code
```

Installation is project-local by default; add `-g` for user-wide installation. The installer supports agents including Claude Code, Codex, Gemini CLI, OpenCode, GitHub Copilot, and Cursor, and handles their installation directories.

For manual installation, copy the entire [`skills/outline-skills/`](skills/outline-skills/) directory, including `references/`, into your agent's skills directory. Examples: `.claude/skills/outline-skills/` for Claude Code or `.agents/skills/outline-skills/` for Codex. Installation locations vary; consult your agent's documentation.

Claude Code users can alternatively install the same skill through the existing plugin:

```text
/plugin marketplace add visualdust/outline-skills
/plugin install outline-skills
```

### 3. Configure Outline

#### Create an API key

Open your Outline workspace settings, go to **API**, and create an API key. Copy the key for the configuration step below; do not share it or commit it to version control.

![Create API key in Outline](docs/images/outline-api-key-setup.jpg)

#### Configure credentials

Set environment variables:

```bash
export OUTLINE_API_KEY="ol_api_..."
export OUTLINE_BASE_URL="https://outline.example.com/api"
```

The base URL should include `/api`. Alternatively, create `~/.outline-skills/config.json`:

```json
{
  "api_key": "ol_api_...",
  "base_url": "https://outline.example.com/api"
}
```

On Unix, protect the config with `chmod 600 ~/.outline-skills/config.json`.

#### Verify the connection

Run:

```bash
outline-cli auth info
```

If successful, the command returns your user and workspace information. For errors, see [Troubleshooting](skills/outline-skills/references/troubleshooting.md).

Now ask your agent to search Outline, create a document, or manage a collection. Compatible agents can discover the skill from its description; explicit invocation syntax depends on the agent.

## CLI examples

```bash
outline-cli search "deployment guide" --limit 5
outline-cli documents info --id "document-id" --fields data.id,data.title,data.revision
outline-cli documents info --id "document-id" --text-only
outline-cli documents info --id "document-id" --full-text
outline-cli documents create --title "Report" --collection-id "collection-id" --text-file ./report.md
outline-cli documents update --id "document-id" --text-file ./report.md
outline-cli comments create --document-id "document-id" --data-file ./comment.md
```

Get only what you need:

- Default summaries are compact JSON without repeated help metadata or expanded document authors.
- `--fields` selects complete values from the original API JSON; dotted paths work across lists, preserving response shape. No unrelated raw fields are returned.
- `documents info --text-only` returns exact full Markdown; `--full-text` includes full Markdown in summary JSON. Neither requires a noisy raw response.
- `--max-text-chars 0` suppresses previews, including search context. Never edit from a truncated preview.
- `--pretty` indents JSON for humans; `--raw` returns the full API response for debugging.

Errors/warnings go to stderr. Put connection flags such as `--base-url` before the subcommand. See [output controls](skills/outline-skills/references/output.md) for field paths and mode constraints.

For Markdown with local images/assets, use `documents create-from-file` instead of `--text-file`, starting with `--dry-run`:

```bash
outline-cli documents create-from-file --file ./report.md --collection-id "collection-id" --dry-run
```

## Documentation

- [Skill instructions](skills/outline-skills/SKILL.md)
- [Command reference](skills/outline-skills/references/commands.md)
- [Output controls](skills/outline-skills/references/output.md)
- [Setup and authentication](skills/outline-skills/references/setup.md)
- [Local Markdown publishing](skills/outline-skills/references/publishing.md)
- [Troubleshooting](skills/outline-skills/references/troubleshooting.md)

## Development

```bash
uv run --extra dev python -m ruff check outline_cli tests
uv run --extra dev python -m mypy outline_cli
uv run --extra dev python -m pytest -q
```

## License

[MIT](LICENSE).
