CLI

The Obris CLI lets you capture screenshots, upload files, and manage your knowledge base directly from the terminal. Bind it to a hotkey for instant screen captures that go straight to your topics.

The CLI is one of several ways to add knowledge to Obris. You can also sync from Google Drive or Notion, save web content with the Chrome extension, or upload files in the dashboard.

Install

Requires Python 3.10+.

pip install obris-cli

Or run directly with uv:

uvx --from obris-cli obris --help

Setup

1. Get your API key

Generate an API key from your Obris experts page. Click the expert you want to use, then go to the API Keys tab.

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

Commands

capture

Take a screenshot and upload it to Obris.

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

Name
--name
Type
string
Description
Set the name for the captured screenshot.
Name
--prompt
Type
flag
Description
Open a dialog to enter a name before capturing.
Name
--topic
Type
string
Description
Topic ID to upload to. Defaults to your Scratch topic.

Screen capture is supported on macOS and Linux. Windows users can use upload instead.

upload

Upload a file to Obris.

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

Name
file
Type
string
Description
Path to the file to upload. Required.
Name
--topic
Type
string
Description
Topic ID to upload to. Defaults to your Scratch topic.

topic list

List topics or knowledge items within a topic.

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

Name
topic_id
Type
string
Description
Optional. If provided, lists knowledge items in that topic.

knowledge move

Move a knowledge item to a different topic.

obris knowledge move <id> --topic <id>

Name
id
Type
string
Description
The knowledge item ID. Required.
Name
--topic
Type
string
Description
The destination topic ID. Required.

knowledge delete

Delete a knowledge item.

obris knowledge delete <id>

Name
id
Type
string
Description
The knowledge item ID to delete. Required.

auth

Authenticate with your Obris API key.

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

Name
--key
Type
string
Description
Your Obris API key. Required.

env

View or set the active environment.

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

Name
name
Type
string
Description
Optional. Environment name to switch to (e.g. dev, prod).

Use --env on any command to override for a single invocation:

obris --env dev capture

Environments

You can configure separate API keys for different environments:

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

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

Use the full path to the obris binary since Alfred does not 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

View on GitHub