Metadata-Version: 2.3
Name: cheso-cli
Version: 0.2.0
Summary: Use Cheso from your terminal or coding agent: research reports, PPT, web pages, posters, videos, images, document translation and format conversion
Keywords: cheso,cli,ai-agent,agent-skills,claude-code,codex,ppt,research-report
Author: cheso
Author-email: cheso <chesoai2026@gmail.com>
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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 :: Office/Business
Classifier: Topic :: Utilities
Requires-Dist: httpx>=0.28.1
Requires-Python: >=3.10
Project-URL: Homepage, https://cheso.ai
Project-URL: Agent Skill, https://github.com/cheso-ai-platform/skills
Description-Content-Type: text/markdown

# cheso-cli

Use [Cheso](https://cheso.ai) from a terminal or a coding agent (Claude Code, Codex, Cursor ...): research reports
with citations, PPT decks, web pages, posters, whiteboards, videos, images, document analysis, translation and
format conversion. Tasks run on Cheso with your own account and credits; result files are downloaded to your
working directory.

## Install

```bash
uv tool install cheso-cli        # or: pipx install cheso-cli
cheso login                      # opens the Cheso sign-in page in your browser; click Allow
cheso skill install              # teaches Claude Code and Codex how to use Cheso
```

Requires Python 3.10+. For the China site (zhishi.qq.com) log in with `cheso login --site cn`; later commands use
the site you logged in to last unless you pass `--site` / `--base-url` or set `CHESO_BASE_URL`.

Then ask your agent, for example: "Use Cheso to turn ./notes.pdf into a 10-slide PPT". Or run it yourself:

```bash
cheso task create --file ./notes.pdf --prompt "Make a 10-slide investor deck in English" --wait
```

## Login

`cheso login` uses OAuth 2.1 (authorization code + PKCE) with a loopback redirect: the CLI listens once on
`http://127.0.0.1:<random port>/callback`, opens the Cheso authorization page, and stores the tokens after you
approve. `--no-browser` only prints the URL; `--port N` fixes the port (for SSH port forwarding:
`ssh -L N:127.0.0.1:N host`, then open the URL locally). The browser must reach the loopback port of the machine
running `cheso`.

Without a browser or a reachable loopback port (SSH sessions, containers, cloud agents), use
`cheso login --device` (OAuth device authorization grant, RFC 8628): it prints a Cheso page and a short code; open
the page on any device, sign in to Cheso, enter the code and click Allow. The CLI polls until you approve (every
5 s, up to `--timeout`, the code itself is valid for 10 minutes). Coding agents split it into two commands that
return quickly: `cheso login --device --no-wait --json` prints the page and code; `cheso login --wait --json` keeps
waiting and can be run again (exit 6 while still waiting). Only enter a code that you started yourself: whoever
approves it lets that CLI act as them.

- Tokens are stored in `$XDG_CONFIG_HOME/cheso/credentials.json` (default `~/.config/cheso/`), one entry per site,
  readable only by you (file 0600, directory 0700), replaced atomically.
- Access tokens are refreshed automatically shortly before they expire, and once more if the server rejects one.
  Refresh tokens rotate and the server revokes the login if an old one is reused, so refreshes are serialized with a
  lock file (`credentials.json.lock`): parallel `cheso` commands share one refresh.
- `cheso logout` revokes the authorization on the server and deletes the local tokens. You can also revoke the CLI
  on the Cheso website under Authorized apps.
- Token precedence: `--token` > `CHESO_API_TOKEN` > stored login. For CI and scripts, set `CHESO_API_TOKEN` to a
  personal Cheso API token; nothing is written to disk.

## Commands

Add `--json` to any command for one JSON document on stdout (progress and warnings go to stderr). Global options
(`--site`, `--base-url`, `--token`, `--json`) may come before or after the command.

| Command | What it does |
|---|---|
| `cheso login [--no-browser] [--port N] [--timeout S]` | Sign in with the browser |
| `cheso login --device [--no-wait] [--timeout S]` | Sign in with a code entered on any device (no browser or loopback needed here) |
| `cheso login --wait [--timeout S]` | Keep waiting for a sign-in started with `--device --no-wait` |
| `cheso logout` | Revoke the login and delete stored tokens |
| `cheso whoami` | Show the account and where the token comes from |
| `cheso credits` | Show available credits |
| `cheso task create --prompt TEXT [--file PATH ...] [--file-id ID ...] [--project ID] [--agent-type cheso\|image_edit] [--wait] [--timeout S] [--output-dir DIR]` | Start a task; checks credits first; `--file` uploads local files; `--wait` waits and downloads the results |
| `cheso task wait ID [--timeout S] [--output-dir DIR] [--no-download]` | Wait for a task (`plan_...`), conversion (`cvt_...`) or translation (`tlj_...`), polling every 3 s and following hand-offs to follow-up tasks; downloads the results |
| `cheso task get ID` | Show status, answer, files or the pending question (no download) |
| `cheso task reply ID [--answer "QUESTION=ANSWER" ...] [--skip]` | Answer the question a task is asking (also `N=ANSWER` by number) |
| `cheso task cancel ID` | Stop a running task |
| `cheso file upload PATH [--project ID]` | Upload a file; prints its `file_id` |
| `cheso file list --project ID` | List a project's files |
| `cheso file download FILE_ID [--version N] [--output-dir DIR]` | Download a file (the latest version by default) |
| `cheso convert FILE_ID --to TYPE [--wait] [--timeout S] [--output-dir DIR]` | Convert a file (e.g. md to pdf/docx, vppt to pptx/pdf, vmotion to mp4); unsupported targets list the valid ones |
| `cheso translate FILE_ID --to LANG [--from LANG] [--wait] [--timeout S] [--output-dir DIR]` | Translate a document (zh, zh-Hant, en, ko, ja, es, fr, ar, ru, pt, de, th) |
| `cheso skill install [--target claude\|codex\|all] [--project] [--force]` | Install the Agent Skill |
| `cheso skill show` | Print the bundled SKILL.md |

Downloads never overwrite: an existing `report.pdf` makes the new file `report (1).pdf`. The default `--timeout`
is 1800 s, counted from the start of the command and covering the result downloads too: no request starts after it
and each one gets at most the time left (uploads and starting the task are not cut short). When it passes the task
keeps running on Cheso and `cheso task wait ID` picks it up again.

The low-level API commands of the first version (`profile`, `project ...`, `session create`, `plan create|get`)
are still available and print raw JSON.

## Exit codes

| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Error |
| 2 | Usage error (bad flags, unsupported conversion target) |
| 3 | The task is waiting for your answer: `cheso task reply` |
| 4 | Login required: `cheso login` or `cheso login --device` (or the token in `CHESO_API_TOKEN` / `--token` was rejected) |
| 5 | Not enough credits (the JSON error carries `topup_url`) |
| 6 | Still running when `--timeout` passed: run `cheso task wait ID` again (for `cheso login --device`: `cheso login --wait`) |
| 7 | Rate limited or project busy; retry later (`retry_after`, `running_task_id` in the JSON error) |
| 8 | The task succeeded, but some result files were not downloaded (`error.file_ids`); `next` downloads just those. A failed task keeps 1 or 5; its files that did not download carry `error` |

## Agent Skill

`cheso skill install` copies `SKILL.md` (shipped inside the package) to:

| Target | User level (default) | `--project` |
|---|---|---|
| Claude Code | `~/.claude/skills/cheso/` | `./.claude/skills/cheso/` |
| Codex | `~/.agents/skills/cheso/` | `./.agents/skills/cheso/` |

An unchanged older copy is upgraded in place; a copy you edited is left alone unless you pass `--force`.

## Privacy

Files you upload and the tasks you start are stored in your Cheso account, in your projects, and use your credits.
The CLI sends your token only to the Cheso site you chose; uploads and downloads to presigned storage URLs carry no
token. Tokens are never printed.

## Environment

| Variable | Use |
|---|---|
| `CHESO_API_TOKEN` | Personal API token (CI, scripts); overrides the stored login |
| `CHESO_BASE_URL` | Override the site URL (e.g. `https://testcheso.ai` for the test environment) |
| `CHESO_DEV_SET` | **Test environment only.** Adds `X-Dev-Set: <value>` to Cheso requests to route them to a developer container; has no effect in production |
| `XDG_CONFIG_HOME` | Where `cheso/credentials.json` lives |

Site precedence: `--base-url` > `--site` > `CHESO_BASE_URL` > the site of the last `cheso login` > `https://cheso.ai`.
Suggested commands (`next`, hints in messages) repeat the `--site` / `--base-url` you passed.

## Development

```bash
cd clients/cli
uv sync
uv run --frozen pytest -q
uvx ruff check . && uvx ruff format --check .   # uses the repository ruff.toml
uv build                                          # wheel and sdist in dist/
```

System tests (case library, pools, runs, reports) live in [`../test-suite`](../test-suite) (`cheso-test`).
