reka-ai/reka-cli

reka-ai/reka-cli

Language: Python

Stars: 0

Forks: 0

Open issues: 0

Created: 2026-03-05T03:55:53Z

Pushed: 2026-03-05T06:14:02Z

Default branch: main

Fork: no

Archived: no

README:

reka

Command-line interface for the Reka Vision Agent API. Upload videos, search content, and ask questions — from a terminal or an AI agent.

The Reka Vision Agent API is a managed service for uploading, processing, and analyzing videos with AI. It handles preprocessing, storage, and embeddings automatically. Key capabilities:

• Video management — upload (by URL or file), retrieve, list, delete
• Semantic search — search video content by natural language query
• Q&A — ask questions about a video and get AI-generated answers
• Tagging — automatic metadata tag generation
• Clip generation — extract shorter clips from longer source videos, and check on the status of the generation

Installation

curl -fsSL https://raw.githubusercontent.com/reka-ai/reka-cli/main/install.sh | bash

To install a specific version:

curl -fsSL https://raw.githubusercontent.com/reka-ai/reka-cli/main/install.sh | bash -s v0.2.0

From source

If you have uv installed, you can install directly from this repo:

uv tool install .

This installs the reka command into uv's tool environment and makes it available on your PATH without needing to activate a virtualenv.

Quick start

# Configure with your API token
reka configure --token

# Upload a video and wait for indexing
VIDEO_ID=$(reka videos upload --url https://example.com/clip.mp4 --name "clip" --wait | jq -r .video_id)

# Search it
reka search --query "person at whiteboard" --video-ids "$VIDEO_ID"

# Ask a question
reka qa --video-id "$VIDEO_ID" --question "What is being discussed?"

Designed for Agents

reka is built to be used by AI agents and scripts, not just humans. Every design decision optimizes for programmatic use.

JSON output by default

All commands output JSON to stdout. Parse it directly without scraping human-readable text:

$ reka videos list
[{"video_id": "abc123", "name": "clip.mp4", "status": "indexed"}, ...]

$ reka videos list | jq '.[].video_id'
"abc123"

Use --format text for human-readable tables when debugging interactively.

Machine-readable CLI contract

Use reka meta --format json to get a stable JSON description of:

• commands and subcommands
• flags/args, required fields, defaults, and env-var bindings
• exit-code mapping
• auth/base-url resolution order

Use --help for human-readable docs; use meta for agent parsing.

Predictable exit codes

Exit code tells you *what kind* of failure occurred — no need to parse error messages:

0 Success
1 Usage error (bad arguments)
2 Authentication failure
3 Permission denied
4 Resource not found
5 Validation error / quota exceeded
6 Rate limit exceeded
7 Server error
8 Timeout
9 Connection error

# Chain commands safely:
VIDEO_ID=$(reka videos upload --url "$URL" --name "test" --wait | jq -r .video_id)
reka search --query "car" --video-ids "$VIDEO_ID"

# Branch on failure type:
reka videos get "$ID" || [ $? -eq 4 ] && echo "video not found"

Structured errors on stderr

Errors always emit JSON to stderr (never mixed with stdout data):

$ reka videos get nonexistent-id
# stdout: (empty)
# stderr: {"error": {"type": "not_found_error", "message": "Video not found"}}
# exit code: 4

No interactive prompts

Every option is a flag. reka never blocks waiting for keyboard input, so it works safely in non-TTY environments (CI, Docker, agent subprocess calls).

Environment variable configuration

Inject credentials without touching config files:

REKA_API_TOKEN=your_token REKA_ENV=staging reka search --query "test"

Async operations with --wait

Some operations (video indexing, generation) complete asynchronously. By default, reka returns immediately with the initial state. Use --wait to block until completion:

# Returns immediately with {"status": "upload_initiated"}
reka videos upload --file clip.mp4 --name "clip" --index

# Blocks until indexed or failed
reka videos upload --file clip.mp4 --name "clip" --index --wait

This lets agents implement their own polling strategy, or delegate it to --wait.

Consistent flags everywhere

--format, --verbose, --env, --timeout, --token work identically on every command. No surprises.

---

Command reference

Global flags

All commands accept these flags:

--format json|text Output format (default: json)
--output-file Write output to file instead of stdout
--verbose Show HTTP request/response debug info on stderr
--env staging|prod API environment (default: prod)
--token Override token (or set REKA_API_TOKEN)
--timeout Request timeout in seconds (default: 30)
--wait Poll until terminal state for async operations
--wait-timeout Max wait time when --wait is used (default: 300)

configure

reka configure --token reka_... # save token for prod
reka configure --token reka_... --env staging

meta

reka meta --format json

videos

reka videos upload --url --name [--index/--no-index] [--group-id ] [--wait]
reka videos upload --file --name [--index/--no-index] [--group-id ] [--wait]
reka videos list
reka videos get
reka videos delete

search

reka search --query [--max-results N] [--video-ids id,id,...] [--threshold F] [--report]
reka search hybrid --query [--max-results N] [--video-ids id,id,...]

qa

reka qa --video-id --question

tag

reka tag --video-id

clip

reka clip create --video-urls [,,...] [--prompt ] [--wait]
reka clip list
reka clip get
reka clip delete

groups

reka groups create --name
reka groups list
reka groups get
reka groups delete

---

Configuration

Resolution order (highest priority first):

| Source | Example | |--------|---------| | --token flag | reka videos list --token reka_... | | REKA_API_TOKEN env var | export REKA_API_TOKEN=reka_... | | ~/.reka/config.json | Written by reka configure |

Config file (~/.reka/config.json):

{"token": "reka_...", "env": "prod"}

Base URL override: set REKA_BASE_URL or --base-url to point at a custom endpoint.

Environments:

• prod →…