Metadata-Version: 2.5
Name: sparki-cli
Version: 1.1.9
Summary: Sparki video editor CLI
Author: Sparki AI
License-Expression: MIT
License-File: LICENSE
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: typer>=0.9.0
Description-Content-Type: text/markdown

# Sparki

AI-powered video editing from the command line. Upload footage, describe what
you want in plain language (or pick a style), and Sparki renders it in the
cloud — no local rendering, no ffmpeg.

`sparki-cli` is a thin HTTP client for the cloud API (`agent-api.sparki.io`).
It is the shared engine behind the Sparki agent skills across several
platforms — **Claude Code**, **Codex**, **Workbuddy**, and **OpenClaw
(Telegram)**. The core commands are identical everywhere; only a few
environment details differ per channel (file upload, result delivery, config
location). Those differences are annotated inline below and marked with a
**📣 Channel note**.

## Installation

```
pip install sparki-cli
```

Or with [uv](https://docs.astral.sh/uv/):

```
uv tool install sparki-cli
```

Upgrade an existing installation with:

```
uv tool install --upgrade sparki-cli
```

## Quick Start

The commands below configure and verify the CLI, demonstrate file upload,
create combined and independent edits, and inspect or delete selected assets.

```bash
sparki setup --api-key YOUR_KEY --channel claude
sparki doctor --channel claude

sparki upload video1.mp4 video2.mp4
sparki upload --dir ./clips

sparki run clip1.mp4 clip2.mp4 clip3.mp4 --mode style-guided --style clips/highlight-reel --output ./sparki-output/highlight-reel.mp4

sparki run clip1.mp4 --mode style-guided --style vlog/daily --output ./sparki-output/clip1-edited.mp4
sparki run clip2.mp4 --mode style-guided --style vlog/daily --output ./sparki-output/clip2-edited.mp4

sparki assets list
sparki assets delete assets/98/old1.mp4 assets/98/old2.mp4
```

## Getting an API key

Use the onboarding page for your integration, then run
`sparki setup --api-key <KEY> --channel <CHANNEL>` or export both
`SPARKI_API_KEY` and `SPARKI_CHANNEL`. Environment variables take precedence
over saved configuration.

> 📣 **Channel note — where the key comes from:**
> - **Claude Code:** https://sparki.io/claude-code-skill (`--channel claude`)
> - **Codex:** https://sparki.io/codex-skill (`--channel codex`)
> - **Workbuddy:** https://sparki.io/workbuddy-skill (`--channel workbuddy`)
> - **OpenClaw (Telegram):** the key is issued through the Sparki Telegram bot
>   (`@Sparki_AI_bot`); users typically already have one from the bot.
>
> When no channel is configured, CLI errors intentionally provide neutral
> setup guidance instead of guessing an onboarding page.

## Commands

| Command | Description |
|---------|-------------|
| `setup` | Save and validate your API key |
| `doctor` | Self-check CLI version, API key, base URL, config directory |
| `upload` | Upload video file(s); positional args, `--file`, or `--dir`; retries + partial success |
| `assets list` | List uploaded assets (alias: `sparki assets`) |
| `assets delete` | Delete uploaded assets by key, `--name`, or `--all --yes` |
| `edit` | Create an edit project from uploaded object keys |
| `status` | Check project status |
| `download` | Download a completed result, optionally revealing it in the native file manager |
| `run` | End-to-end: upload → edit → download, with optional native file reveal |
| `history` | List recent projects |
| `upload-tg` | **(Telegram only)** Return the Telegram Mini App upload link |

## Edit Modes

- **style-guided** — Choose from preset styles (e.g. `vlog/daily`, `clips/highlight-reel`)
- **prompt-driven** — Describe what you want in natural language
- **style-clone** — Clone the style of a reference video

## Styles

Styles are `category/sub-style`. The full catalog:

| Style | Best for |
|---|---|
| `vlog/daily` | Day-in-the-life, event recaps, BTS |
| `vlog/travel` | Vacations, road trips, city breaks |
| `vlog/sports` | Game highlights, performance reels |
| `vlog/chill-vibe` | Morning routines, slow living, aesthetic |
| `clips/long-to-short` | Turn a long video's best moments into a short |
| `clips/highlight-reel` | Beat-synced montage of best moments |
| `narrative/podcast-interview` | Trim filler/pauses from podcasts & interviews |
| `narrative/funny-commentary` | Written & voiced comedic commentary |
| `narrative/master-storyteller` | Dramatic narration with emotional arcs |
| `tools/ai-captions` | Timed, styled captions from dialogue |
| `tools/ai-translation` | Captions translated to a target language |

> ⚠️ Category is `clips`, not `montage`. Unknown styles are rejected server-side
> with `INVALID_STYLE`.

## Providing video files

> 📣 **Channel note — how footage gets into Sparki:**
> - **Claude Code:** pass a local file path directly to `sparki run` / `sparki upload`.
> - **Workbuddy:** the user uploads through the Workbuddy UI; then use
>   `sparki assets list` to get the `object_key` and `sparki edit <object_key>`.
> - **OpenClaw (Telegram):** users cannot send video files in chat. Use a local
>   file path, or `sparki upload-tg` to get a Mini App upload link.

## Multi-file upload

`sparki upload` and `sparki run` accept multiple files through explicit paths
or a directory scan:

- **Positional args** (recommended): `sparki upload a.mp4 b.mp4`
- **Directory** (single-level): `sparki upload --dir ./clips`
- **--file** (deprecated alias): `sparki upload --file a.mp4 --file b.mp4`

Multiple positional files combine into **one** output project. To produce **N**
independent outputs, call the command once per file.

Reliability options:

- `--max-retries N` (default 3; 0 disables) — per-file retries on network errors / 429 / 5xx
- `--upload-timeout SEC` (default 600) — per-file timeout
- `--quiet` — suppress stderr progress output
- `--strict` (run only) — abort if any source file fails upload (default: proceed with successful ones)

## Output & delivery

By default `sparki run` / `sparki download` write the result to a local file.
Pass `--output <path>` to control where, and pass `--reveal` to open the native
file manager with the result selected after download. Use `--reveal` only when
the CLI is running in a local desktop environment with GUI access. The CLI keeps
`result_url` in its JSON output for API compatibility, but interactive agents
should deliver the downloaded local file rather than presenting that URL.

Native reveal uses Finder on macOS, Explorer on Windows, and the freedesktop
FileManager1 interface on Linux. Linux falls back to opening the containing
folder with `xdg-open` when the active file manager cannot select an item.
Reveal failures are reported in `file_manager` but do not fail the download.
Browser-only and remote environments cannot open a file manager on the user's
local computer, so they must report that limitation instead of claiming the
folder was opened. `file_path` preserves the legacy relative-or-absolute path
representation for backward compatibility, while `local_path` and
`output_directory` are absolute so the user can still locate the output
manually.

> 📣 **Channel note — config & output locations:**
> The config file and the default output directory currently live under
> `~/.openclaw/` **on every channel** (this is a legacy path name — it does
> **not** require OpenClaw to be installed):
> - Config: `~/.openclaw/config/sparki.json`
> - Default output (when `--output` is omitted): `~/.openclaw/workspace/sparki/videos/<task_id>.mp4`
>
> Because the default is a fixed absolute path, agents running in a project
> workspace (Claude Code, Workbuddy) should **always pass `--output ./...`** to
> keep results in the working directory.

> 📣 **Channel note — the `delivery_hint` field:**
> Results retain `delivery_hint` for integrations that already depend on it.
> Codex and other local-file agents must not use `link_only` to expose
> `result_url`; they should always use `local_path`, `output_directory`, and
> `file_manager` for delivery. The `telegram_direct` and `link_only` values are
> historical compatibility labels, not local-delivery instructions.

## Error codes

All commands return structured JSON: `{"ok": false, "error": {"code", "message", "action"}}`.
Common codes: `AUTH_FAILED`, `QUOTA_EXCEEDED`, `STORAGE_FULL`, `FILE_TOO_LARGE`,
`INVALID_STYLE`, `INVALID_MODE`, `RENDER_TIMEOUT`, `TASK_NOT_FOUND`,
`NETWORK_ERROR`, `NO_MATCH`, `DOCTOR_FAILED`. Each `action` field tells you (or
the agent) what to do next.

## Notes

- Formats: mp4, mov only. Max file size: 3GB.
- Processing typically takes 5–20 minutes.
- API rate limit: 3 seconds between requests (server-enforced).
- For long videos (30+ min): `--timeout 7200`.

## Links

- Website: https://sparki.io
- Claude Code: https://sparki.io/claude-code-skill
- Codex: https://sparki.io/codex-skill
- Workbuddy: https://sparki.io/workbuddy-skill
- Support: support@sparki.io
