Metadata-Version: 2.5
Name: sparki-cli
Version: 1.1.7
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**, **OpenClaw (Telegram)**, and **Workbuddy**. 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 to the latest release
uv tool install --upgrade sparki-cli
```

## Quick Start

```bash
# Configure your API key and verify the install
sparki setup --api-key YOUR_KEY
sparki doctor

# Upload one or multiple files (positional args; shell glob works)
sparki upload video1.mp4 video2.mp4
sparki upload *.mp4
sparki upload --dir ./clips

# Edit: combine multiple source clips into ONE output project
sparki run clip1.mp4 clip2.mp4 clip3.mp4 \
  --mode style-guided --style clips/highlight-reel

# Edit: loop for N independent outputs
for f in *.mp4; do
  sparki run "$f" --mode style-guided --style vlog/daily
done

# Clean up storage
sparki assets list
sparki assets delete assets/98/old1.mp4 assets/98/old2.mp4
sparki assets delete --all --yes   # wipe everything
```

## Getting an API key

Get a key at **https://sparki.io/doc/api** (the "Get API Key" flow), then either
run `sparki setup --api-key <KEY>` or export `SPARKI_API_KEY` in your
environment (the env var takes precedence over the saved config).

> 📣 **Channel note — where the key comes from:**
> - **Claude Code / Workbuddy:** get the key from https://sparki.io/doc/api.
> - **OpenClaw (Telegram):** the key is issued through the Sparki Telegram bot
>   (`@Sparki_AI_bot`); users typically already have one from the bot.

## 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 completed result |
| `run` | End-to-end: upload → edit → download (accepts multiple positional files) |
| `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 three ways:

- **Positional args** (recommended): `sparki upload a.mp4 b.mp4`
- **Shell glob**: `sparki upload *.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 in a loop.

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. Every result also carries a
`result_url` (a CDN link that **expires after 24 hours** — download promptly).

> 📣 **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 include a `delivery_hint`. `telegram_direct` means "small enough to
> send inline" and `link_only` means "too large, share the `result_url`". The
> `telegram_direct` label is historical — outside Telegram, just read it as
> "small file, deliver directly" vs. "large file, share the link."

## 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
- Get an API key: https://sparki.io/doc/api
- Support: support@sparki.io
