xevol 0.12.1 → 0.12.3

package/README.md

@@ -1,407 +1,120 @@
-# xevol
+# xevol CLI
 
-**Transcribe, analyze, and explore YouTube and web content from your terminal.**
+Terminal client for Xevol content execution.
 
-[![npm version](https://img.shields.io/npm/v/xevol)](https://www.npmjs.com/package/xevol)
-[![License](https://img.shields.io/badge/license-proprietary-blue)](https://xevol.com)
-[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+Use it to ingest content, run analysis (spikes), manage prompts, inspect usage, and work across personal/team workspaces.
 
-Paste a YouTube or web URL, get AI-powered transcription and analysis — no API keys, no local GPU, no tool chaining.
-
-## Quick Demo
-
-```bash
-$ xevol add https://youtube.com/watch?v=oOylEw3tPQ8 --analyze facts
-
-⠋ Processing... (12s)
-✔ "Cursor CEO: Going Beyond Code" (37:29)
-
-─── facts ───
-• Cursor reached $100M ARR in 20 months
-• 40-50% of code in Cursor is AI-generated
-• Team hired first 10 employees over 6 months deliberately
-• Pivoted from AI-CAD to AI coding tools
-
-✔ Done
-```
-
-## Installation
+## Install
 
 ```bash
 npm install -g xevol
-```
-
-Or run without installing:
-
-```bash
+# or
 npx xevol
-```
-
-or install with brew:
-
-```bash
+# or
 brew install xevol/tap/xevol
 ```
 
-Requires Node.js 18+.
+Requires **Node.js >= 20**.
 
-## Quick Start
+## Quick start
 
 ```bash
-# 1. Authenticate
+# 1) Login (device flow)
 xevol login
 
-# 2. Add a YouTube video or web page (waits for completion by default)
-xevol add "https://youtube.com/watch?v=abc123"
-# or
-xevol add "https://example.com/article"
+# 2) Add content from URL (YouTube routes to /v1/add, other URLs to /v1/create)
+xevol add "https://youtube.com/watch?v=oOylEw3tPQ8"
 
-# 3. Analyze it
-xevol analyze <id> --prompt facts
+# 3) Run analysis
+xevol analyze <transcription-id> --prompt facts
 
-# 4. View the transcript
-xevol view <id>
+# 4) View content
+xevol view <transcription-id>
 ```
 
-## Commands
-
-| Command   | Description                                     |
-| --------- | ----------------------------------------------- |
-| `login`   | Authenticate via device flow (opens browser)    |
-| `logout`  | Clear stored credentials                        |
-| `whoami`  | Show current user, plan, and usage              |
-| `add`     | Add a URL (YouTube or website) for processing |
-| `list`    | List your transcriptions                        |
-| `locations` | List your Xevol Coordinates location history  |
-| `view`    | View a transcription summary or full transcript |
-| `analyze` | Generate AI analysis using a prompt             |
-| `prompts` | Manage prompts (list/create/update/delete)       |
-| `stream`  | Stream analysis output via SSE                  |
-| `resume`  | Resume a previous streaming session             |
-| `config`  | View or edit CLI configuration                  |
-
-All commands support `--json` for machine-readable output.
-
-## Command Details
-
-### `xevol login`
+## Workspace model
 
-Authenticate using the device code flow — opens your browser, you confirm, done.
+Xevol CLI supports workspace switching:
 
 ```bash
-# Interactive device flow
-xevol login
-
-# Token-based (CI / headless)
-xevol login --token <token>
-
-# Or set via environment variable
-export XEVOL_TOKEN=<token>
+xevol workspace list
+xevol workspace switch <workspace-id>
 ```
 
-### `xevol add`
+When a workspace is selected, CLI sends `X-Workspace-Id` automatically for workspace-aware API routes.
 
-Add a URL (YouTube or website) for processing.
+## Command map
 
-```bash
-# Add and wait for processing (default)
-xevol add "https://youtube.com/watch?v=abc123"
+### Auth
+- `xevol login` — device auth flow (or `--token` for headless/CI)
+- `xevol logout` — revoke token + clear local config
+- `xevol whoami` — current authenticated account
 
-# Add a web page
-xevol add "https://example.com/article"
+### Ingestion & content
+- `xevol add <url>` — URL ingestion (YouTube + non-YouTube)
+- `xevol create [text]` — create from text/file/url/stdin/editor
+- `xevol list` — list transcriptions
+- `xevol view <id>` — view summary/content
+- `xevol delete <id>` — delete transcription
+- `xevol open <id>` — open item in browser
 
-# Fire-and-forget (returns ID immediately)
-xevol add "https://youtube.com/watch?v=abc123" --no-wait
+### Analysis & prompts
+- `xevol analyze <id> --prompt <promptId>` — create/read spike output
+- `xevol stream <spikeId>` — SSE stream spike content
+- `xevol resume <transcriptionId>` — resume interrupted stream session
+- `xevol prompts ...` — prompt CRUD/list/get
 
-# Specify language
-xevol add "https://youtube.com/watch?v=abc123" --lang de
+### Usage, exports, locations
+- `xevol usage` — plan + usage snapshot
+- `xevol export <id> --format json|markdown|text` — export content locally
+- `xevol whereami` — latest Xevol Coordinates location
+- `xevol locations` — Xevol Coordinates history
 
-# Process and analyze in one step
-xevol add "https://youtube.com/watch?v=abc123" --analyze facts
-
-# Analyze with multiple prompts
-xevol add "https://youtube.com/watch?v=abc123" --analyze facts,advice
-
-# Stream analysis output in real time
-xevol add "https://youtube.com/watch?v=abc123" --analyze facts --stream
-```
+### Interface
+- `xevol tui` — interactive terminal UI
 
-| Flag                  | Description                                           |
-| --------------------- | ----------------------------------------------------- |
-| `--no-wait`           | Return immediately without waiting                    |
-| `--lang <code>`       | Language code (e.g. `en`, `de`, `ja`)                 |
-| `--analyze <prompts>` | Comma-separated prompt IDs to run after processing |
-| `--stream`            | Stream analysis output via SSE                        |
-| `--json`              | JSON output                                           |
+## Common flags
 
-### `xevol list`
+- `--json` machine-readable output
+- `--token <token>` override auth token per command
+- `--no-color` disable ANSI colors
 
-List your transcriptions.
+## Examples
 
 ```bash
-# Default table view
-xevol list
+# Add + analyze + stream
+xevol add "https://youtube.com/watch?v=..." --analyze facts,summary --stream
 
-# Pagination
-xevol list --page 2 --limit 50
+# Create from file
+xevol create --file notes.md --title "Research notes"
 
-# Filter by status
-xevol list --status completed
-
-# Machine-readable formats
+# List in JSON
 xevol list --json
-xevol list --csv
-```
-
-| Flag           | Description      |
-| -------------- | ---------------- |
-| `--page <n>`   | Page number      |
-| `--limit <n>`  | Results per page |
-| `--status <s>` | Filter by status |
-| `--json`       | JSON output      |
-| `--csv`        | CSV output       |
-
-### `xevol locations`
-
-List your location history from Xevol Coordinates.
-
-```bash
-# Default view
-xevol locations
-
-# Pagination
-xevol locations --page 2 --limit 50
-
-# Filter by time window
-xevol locations --since 2026-01-01T00:00:00Z --until 2026-01-31T23:59:59Z
-
-# Include exact latitude/longitude
-xevol locations --exact
-
-# Machine-readable formats
-xevol locations --json
-xevol locations --csv
-```
-
-| Flag            | Description                                 |
-| --------------- | ------------------------------------------- |
-| `--page <n>`    | Page number                                 |
-| `--limit <n>`   | Results per page                            |
-| `--since <iso>` | Include records at/after this ISO datetime  |
-| `--until <iso>` | Include records at/before this ISO datetime |
-| `--exact`       | Include exact latitude/longitude columns    |
-| `--json`        | JSON output                                 |
-| `--csv`         | CSV output                                  |
-
-### `xevol view`
-
-View a transcription's summary or full transcript.
 
-```bash
-# Summary view
-xevol view abc123def45
-
-# Full transcript (pipe-friendly)
-xevol view abc123def45 --raw
-
-# Clean transcript (processed content)
-xevol view abc123def45 --clean
-
-# JSON output
-xevol view abc123def45 --json
+# Export markdown
+xevol export <id> --format markdown --output summary.md
 ```
 
-| Flag      | Description                    |
-| --------- | ------------------------------ |
-| `--raw`   | Print the full transcript text |
-| `--clean` | Use cleaned/processed content  |
-| `--json`  | JSON output                    |
+## Config
 
-### `xevol analyze`
+CLI config is stored in:
 
-Generate AI-powered analysis of a transcription.
+- `~/.xevol/config.json`
 
-```bash
-# Analyze with a specific prompt
-xevol analyze abc123def45 --prompt facts
-
-# Use a different language for output
-xevol analyze abc123def45 --prompt facts --lang de
-
-# JSON output
-xevol analyze abc123def45 --prompt facts --json
-```
+Includes token, API URL, selected workspace, and defaults.
 
-| Flag            | Description                       |
-| --------------- | --------------------------------- |
-| `--prompt <id>` | Prompt to use (default: `review`) |
-| `--lang <code>` | Output language                   |
-| `--json`        | JSON output                       |
+## Notes
 
-Use `xevol prompts` to see all available prompts.
+- Execution environment unification is in progress across API/CLI/mobile.
+- Workspace-aware resources already respect selected workspace context.
+- Usage/limit reporting follows API-provided scope during rollout.
 
-### `xevol prompts`
-
-Manage prompts (list/create/update/delete).
+## Development
 
 ```bash
-# List prompts
-xevol prompts
-xevol prompts list --json
-xevol prompts list --csv
-
-# View a prompt
-xevol prompts get <prompt-id>
-
-# Create a prompt
-xevol prompts create --name "Summary" --text "Summarize this transcript"
-xevol prompts create --name "Ideas" --file prompt.md
-cat prompt.md | xevol prompts create --name "Ideas"
-
-# Update a prompt
-xevol prompts update <prompt-id> --name "New name"
-xevol prompts update <prompt-id> --text "Rewrite this prompt"
-xevol prompts update <prompt-id> --file prompt.md
-xevol prompts update <prompt-id> --editor
-
-# Delete a prompt
-xevol prompts delete <prompt-id>
+bun install
+bun run dev
+bun run build
+bun run typecheck
+bun run lint
 ```
-
-### `xevol stream`
-
-Stream analysis output in real time via SSE.
-
-```bash
-xevol stream <spike-id>
-xevol stream <spike-id> --last-event-id <id>
-```
-
-### `xevol resume`
-
-Resume a previously interrupted streaming session.
-
-```bash
-xevol resume <transcription-id>
-```
-
-### `xevol config`
-
-View or edit CLI configuration.
-
-```bash
-# Show all config
-xevol config
-
-# Get a value
-xevol config get apiUrl
-
-# Set a value
-xevol config set default.lang de
-xevol config set default.limit 50
-```
-
-Available config keys:
-
-| Key             | Description                  |
-| --------------- | ---------------------------- |
-| `apiUrl`        | Base API URL                 |
-| `default.lang`  | Default output language      |
-| `default.limit` | Default page size for `list` |
-| `api.timeout`   | API request timeout (ms)     |
-
-## Output Formats
-
-### Table (default)
-
-```
-┌─────────────┬────────────────────────────────┬──────────┬──────────┐
-│ ID          │ Title                          │ Duration │ Status   │
-├─────────────┼────────────────────────────────┼──────────┼──────────┤
-│ abc123def45 │ Cursor CEO: Going Beyond Code  │ 37:29    │ ✔ done   │
-│ xyz789ghi01 │ Naval on Happiness             │ 12:03    │ ⠋ proc…  │
-└─────────────┴────────────────────────────────┴──────────┴──────────┘
-```
-
-### JSON (`--json`)
-
-```bash
-xevol list --json | jq '.list[] | select(.channelTitle == "Y Combinator")'
-xevol analyze abc123 --prompt facts --json | jq '.spikes[0].content'
-```
-
-### CSV (`--csv`)
-
-```bash
-xevol list --csv > transcriptions.csv
-xevol prompts --csv
-```
-
-## Streaming
-
-Analysis output streams in real time via Server-Sent Events (SSE). Use `--stream` with `add` to watch analysis as it's generated:
-
-```bash
-xevol add "https://youtube.com/watch?v=..." --analyze facts --stream
-```
-
-If a stream is interrupted, resume it:
-
-```bash
-xevol resume <transcription-id>
-```
-
-## Authentication
-
-xevol uses a device authorization flow, similar to `gh auth login`:
-
-1. Run `xevol login`
-2. A code is displayed and your browser opens
-3. Enter the code to authorize
-4. The CLI stores your token locally at `~/.xevol/`
-
-For CI/CD or headless environments, use token-based auth:
-
-```bash
-xevol login --token <token>
-# or
-export XEVOL_TOKEN=<token>
-```
-
-Check your auth status:
-
-```bash
-xevol whoami
-```
-
-## Piping & Scripting
-
-```bash
-# Pipe transcript to other tools
-xevol view <id> --raw | wc -w
-
-# JSON output for scripting
-xevol list --json | jq '.list | length'
-
-# Export to CSV
-xevol list --csv > my-transcriptions.csv
-```
-
-## Global Options
-
-| Flag              | Description                              |
-| ----------------- | ---------------------------------------- |
-| `--token <token>` | Override auth token for a single command |
-| `--no-color`      | Disable colored output                   |
-| `--json`          | Machine-readable JSON output             |
-| `-V, --version`   | Print version                            |
-| `-h, --help`      | Show help                                |
-
-## Links
-
-- **Website**: [xevol.com](https://xevol.com)
-- **Issues**: [github.com/xevol/xevol-cli/issues](https://github.com/xevol/xevol-cli/issues)
-
-## License
-
-Proprietary — see [xevol.com](https://xevol.com) for terms.