obris-cli 0.1.1

CLI for capturing screenshots and managing knowledge in Obris

Obris CLI

A command-line tool for capturing screenshots and managing knowledge in Obris, your personal knowledge layer for AI. Save content to organized topics so you never start another AI chat from zero again.

Install

Requires Python 3.10+.

pip install obris-cli

Or run directly with uv:

uvx obris-cli --help

Optional: macOS notifications

For desktop notifications with deep linking to your uploaded content:

brew install terminal-notifier

Setup

1. Get your API key

Generate an API key from your Obris dashboard. Don't have an account? Sign up.

2. Authenticate

obris auth --key <your-api-key>

This saves your key locally to ~/.obris/config.json and detects your Scratch topic (the default destination for captures).

Environments

You can configure separate API keys for prod and dev side by side:

obris auth --key <prod-key>              # saves to prod (default)
obris --env dev auth --key <dev-key>     # saves to dev

Use --env on any command to override the active environment:

obris --env dev capture
obris --env dev topic list

Set the default environment:

obris env dev    # switch default to dev
obris env        # show current default

Usage

Capture a screenshot

obris capture                       # screenshot + upload to Scratch
obris capture --name "my pic"       # explicit name
obris capture --prompt              # prompt for a name via dialog
obris capture --topic <id>          # upload to a specific topic

Upload a file

obris upload photo.png              # upload to Scratch
obris upload photo.png --topic <id> # upload to a specific topic

Manage topics

obris topic list                    # list all topics
obris topic list <topic_id>         # list knowledge in a topic

Manage knowledge

obris knowledge move <id> --topic <id>  # move to another topic
obris knowledge delete <id>             # delete a knowledge item

Hotkeys

Bind keyboard shortcuts to capture commands using any automation tool — Alfred, Raycast, Keyboard Maestro, macOS Shortcuts, etc.

Example: Alfred

Create a workflow with a Hotkey trigger connected to a Run Script action (language: /bin/zsh):

Quick capture:

/full/path/to/obris capture

Capture with name prompt:

/full/path/to/obris capture --prompt

Tip: Use the full path to the obris binary since Alfred doesn't load your shell profile. Run which obris to find it.

Platform support

Platform	Capture	Upload / Topics / Knowledge
macOS	Yes	Yes
Linux	Yes	Yes
Windows	No	Yes

Development

git clone https://github.com/obris-dev/obris-cli.git
cd obris-cli
uv sync

Run commands locally without installing:

uv run obris --env dev auth --key <your-api-key>
uv run obris capture
uv run obris topic list

Publishing

make publish   # build and publish to PyPI

Privacy Policy

This CLI sends your Obris API key to the Obris API (api.obris.ai) to authenticate requests. It uploads files and retrieves topic and knowledge data from your account. No data is stored beyond the local config file at ~/.obris/config.json.

For the full privacy policy, see obris.ai/privacy.

Support

For issues or questions, contact [e-mail] or open an issue on GitHub.

License

MIT