Skip to content

cli.md

Latest commit

 

History

History
192 lines (141 loc) · 7.44 KB

cli.md

File metadata and controls

192 lines (141 loc) · 7.44 KB

Command-Line Reference

For users who prefer the terminal, Oversight ships a comprehensive oversight CLI that mirrors most of what the web UI offers. Install once, then manage projects, tasks, workflows, agents, and knowledge from your shell — pipe-friendly output, scriptable, SSH-safe.

Getting started

Build the CLI binaries:

cargo build -p oversight-cli --release
# Binary lands at target/release/oversight

First-time setup:

# Log in (creates ~/.config/oversight/config.toml with your bearer token)
oversight auth login --username admin

# Or point the current profile at a non-default server as part of login
oversight auth login --server https://oversight.prod.example --username admin

# Pick a default project so you don't have to pass --project every time
oversight projects list
oversight projects use <project-id>

# Shell tab-completion (one-time)
oversight completion bash > /etc/bash_completion.d/oversight       # or zsh / fish / power-shell / elvish

Global options

These flags are accepted on every subcommand:

Flag Purpose
--profile <name> Switch the active config profile for this invocation
--server <url> Override the server URL
-p, --project <id> Override the active project
-f, --format <fmt> Output format: auto (default), table, json, yaml, csv, name

auto picks table when stdout is a TTY and json when piped — so oversight tasks list | jq works without extra flags.

--format is honored by the structured commands (for example list / describe / most create / update verbs). A few commands intentionally emit specialized output instead:

  • completion prints the shell completion script
  • docs show prints raw Markdown
  • tasks tree prints an ASCII tree
  • tasks watch streams SSE events
  • confirmation-style actions such as projects use, tasks comment, tasks attach, and tasks relate print a short human confirmation line

For scripting, prefer the structured verbs plus --format json, then follow up with describe / list when a confirmation-only action is involved.

Subcommand overview

Group What it does
auth Log in/out, show current user
config Manage ~/.config/oversight/config.toml + named profiles
completion Print a shell completion script
projects List / describe / create / set default project; manage members
tasks 14 task verbs: list, tree, board, describe, create, transition, comment, update, delete, assign, relate, attach, decompose, watch
workflows Inspect or manage workflows and their automation rules (CRUD + rules add/remove)
agents Browse / manage agent definitions, run on a task, manage memory
inbox Clear pending tool-permission approvals; accept/reject proposed tasks
cycles Sprints / iterations — CRUD
milestones Goals — CRUD
schedules Cron-scheduled agent runs — CRUD + run-now
collections Knowledge bases
docs Knowledge documents (Markdown content)
search Cross-entity search (tasks, documents, projects)
system Health check, global stats, agent activity log
init / run / worker Local CLI agent integration (legacy path, unchanged)

Run oversight <group> --help for detailed verbs and flags on any group.

Common recipes

Triage the backlog:

oversight tasks list --status backlog --priority P0

See the board:

oversight tasks board

Inspect a task tree:

oversight tasks tree TASK-abc123

Create a task, then transition it:

oversight tasks create --title "Add password reset" --type feature
# → task-4f2e...
oversight tasks transition task-4f2e... in_progress

If you also pass --description / --description-file, Oversight stores the linked task document in the project's General collection by default. When you render task output as JSON (-f json), the response includes the linked doc_id.

Workflow resolution follows the active project (oversight projects use ... or --project). In a brand-new project, create a matching workflow for the task type first (for example feature / implementation) or pass --workflow <id> explicitly.

Approve a pending tool-permission request:

oversight inbox approvals list               # list pending
oversight inbox approvals approve <tool-call-id>

Comment on a task via $EDITOR:

oversight tasks comment task-4f2e...         # opens $EDITOR for Markdown

Pipe JSON to jq for scripting:

oversight tasks list --format json \
  | jq '.[] | select(.status == "backlog") | .id' \
  | xargs -I {} oversight tasks transition {} ready

Switch between environments:

oversight config configurations create prod --server https://oversight.prod.example
oversight auth login --profile prod
oversight --profile prod tasks list         # one-off override
oversight config use-profile prod           # switch persistent default

Search knowledge base:

oversight search "oauth login" --types document --limit 10

For multiple entity types, pass a comma-separated list:

oversight search "oauth login" --types task,document,project --limit 10

Monitor agent activity:

oversight system status                     # server health
oversight system stats                      # doc / edge counts
oversight system activities --agent coder --limit 20

Configuration file

The CLI config lives at:

Platform Path
Linux / macOS ~/.config/oversight/config.toml
Override OVERSIGHT_CONFIG_HOME=/path/to/dir

Tokens are stored in the OS keyring (libsecret / Keychain / Credential Manager). On systems without a keyring, the CLI falls back to a chmod 600 file beside config.toml.

Full verb list

The sections below show every verb. For details run oversight <subcommand> --help.

  • auth: login, logout, whoami
  • config: set, get, list, unset, use-profile, configurations {list,create,describe,delete}
  • completion: bash, zsh, fish, power-shell, elvish
  • projects: list, describe, create, use, members {list,add,remove}
  • tasks: list, tree, board, describe, create, transition, comment, update, delete, assign, relate, attach, decompose, watch
  • workflows: list, describe, create, update, delete, rules {list,add,remove}
  • agents: list, describe, stats, create, update, delete, run, memory {show,export,import,reset}
  • inbox approvals: list, approve, deny
  • inbox proposals: list, accept, reject
  • cycles: list, describe, create, update, delete
  • milestones (goals): list, describe, create, update, delete
  • schedules: list, describe, create, update, delete, run-now
  • collections (knowledge bases): list, describe, create, delete (create requires --when-to-read, --when-to-write, --doc-requirements)
  • docs: list, describe, show, create, delete (create requires --collection; show emits raw Markdown)
  • search <query>: --mode lexical/semantic/hybrid, --types task,document,project, --limit
  • system: status, stats, activities
  • init --agent claude|codex|hermes (legacy CLI agent integration)
  • run <agent-type> (launch a local CLI agent; --task / --title require a reachable server)
  • worker (start a worker daemon; distributed mode)