Metadata-Version: 2.4
Name: lithora-cli
Version: 0.2.0
Summary: Command-line interface for the Lithora REST API (the agent-grade control plane)
Author-email: Lithora <support@lithora.io>
License-Expression: MIT
Project-URL: Homepage, https://lithora.io
Project-URL: Documentation, https://github.com/AADI0009/SaaS-App/tree/main/cli
Project-URL: Repository, https://github.com/AADI0009/SaaS-App
Project-URL: Issues, https://github.com/AADI0009/SaaS-App/issues
Project-URL: API, https://api.lithora.io
Keywords: lithora,cli,project-management,api,agent
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13
Requires-Dist: keyring>=24
Requires-Dist: lithora>=0.1
Provides-Extra: yaml
Requires-Dist: pyyaml>=6; extra == "yaml"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: responses>=0.23; extra == "dev"
Dynamic: license-file

# lithora — the Lithora CLI

The terminal-native, agent-grade control plane for [Lithora](https://lithora.io).
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`](../sdk/python) Python SDK (one shared HTTP core,
nothing vendored). `v0.2` — **beta**.

## Install

```bash
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)

```bash
# 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 you@example.com
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

```bash
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

```bash
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)

```yaml
- 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`](EXPANSION_PLAN.md) for the roadmap.

## License

MIT — see [LICENSE](LICENSE).
