lithora-cli 0.2.0

Command-line interface for the Lithora REST API (the agent-grade control plane)

lithora — the Lithora CLI

The terminal-native, agent-grade control plane for Lithora. Manage teams, projects, issues, automations — and drive the confirmation-gated AI agent — without leaving your shell or your CI pipeline.

Built on the official lithora Python SDK (one shared HTTP core, nothing vendored). v0.2 — beta.

Install

pipx install lithora-cli         # recommended (isolated)
# or
pip install lithora-cli

This installs the lithora command. Requires Python 3.9+. Optional: keyring (used automatically for OS-keychain token storage; falls back to a 600-mode file).

Quickstart (every command here is real)

# 1. Point at your API (defaults to https://api.lithora.io)
export LITHORA_BASE_URL=http://localhost:8000          # optional, local dev

# 2. Log in (password is prompted securely; token → OS keychain or 600-mode file)
lithora login --email [e-mail]
lithora whoami
lithora doctor                                         # diagnose auth/connectivity

# 3. Projects & issues
lithora teams list
lithora projects create --name "Q3 Launch" --team <team_id>
lithora tasks create --title "Wire up billing" --project <project_id> --priority high
lithora tasks list --project <project_id> --status todo
lithora tasks status <task_id> in_progress

# 4. The AI agent — propose → approve in the terminal → apply
lithora ai "break the autosave issue into a parent task and subtasks"
#   → renders the plan, asks "Approve? [y]es / [n]o", then applies on approval.

# 5. Automations, GitHub, the work graph
lithora automations list
lithora automations execute <automation_id>
lithora work-items graph --team <team_id>
lithora work-items pr-status <task_id>

The confirmation gate (the keystone)

The agent never writes without your approval. lithora ai "<prompt>" shows the proposed plan and waits:

ACTION PLAN  (requires confirmation)
  1. + task: Add autosave to the editor   [acme/web#418]
       - subtask: Persist drafts to localStorage
       - subtask: Debounced autosave on change
  Summary: Agent will create 1 task + 3 subtasks
Approve? [y]es / [n]o:

• Interactive: y applies it, n discards it.
• CI / non-interactive: add --yes to auto-approve, e.g. lithora ai chat "<prompt>" --yes (the plan is still printed first). lithora ai "<prompt>" is shorthand for lithora ai chat, so the flag works on both forms. Without a TTY and without --yes, the CLI refuses to write and exits 2 — so an unattended run can never silently mutate your workspace.
• Overnight digests: lithora ai pending lists plans the scheduled triage agent staged; approve one with lithora ai confirm <action_id> --session <sid>.

Output & scripting

lithora tasks list --project P -o json | jq '.tasks[].title'   # stable JSON
lithora -o json automations list                               # machine-readable

• --output table (default, colorized on a TTY) · --output json (stable, for CI) · --output yaml.
• Exit codes: 0 ok · 2 usage / confirmation-needed · 3 auth · 4 not-found · 5 conflict · 22 invalid input · 130 interrupted.

Profiles, config & tokens

lithora profile list
lithora --profile work whoami            # target a different account/org
lithora token create --name "GitHub CI" --scope tasks:write --expires-in-days 90
lithora token list
lithora token revoke <token_id>

• Config lives in ~/.lithora/config.json (dir 700 / file 600). The bearer token is stored in your OS keychain when available, else the 600-mode file.
• Precedence: flag > env (LITHORA_TOKEN/LITHORA_BASE_URL/LITHORA_PROFILE) > profile > default.
• The password is never accepted as a flag value (argv/history leak). Use the prompt or --password-stdin in CI.

CI example (GitHub Actions)

- name: Create a Lithora issue from a failing build
  if: failure()
  env:
    LITHORA_TOKEN: ${{ secrets.LITHORA_PAT }}      # a scoped PAT (lithora token create)
  run: |
    pipx install lithora-cli
    lithora tasks create --title "CI failed on ${{ github.sha }}" \
      --project "$LITHORA_PROJECT" --priority high -o json

Command map

login · logout · whoami · doctor · --version teams · projects · tasks · work-items · automations · github · search ai (chat / pending / confirm / sessions) · token · profile

Run lithora <group> --help for the full surface. See EXPANSION_PLAN.md for the roadmap.

License

MIT — see LICENSE.