Metadata-Version: 2.5
Name: visionstory-cli
Version: 0.0.7
Summary: Command-line interface for the VisionStory API - AI talking-avatar video generation.
Project-URL: Homepage, https://openapi.visionstory.ai/docs
Project-URL: Documentation, https://openapi.visionstory.ai/docs/guides/cli
Author-email: VisionStory <register@visionstory.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,avatar,cli,command-line,talking-avatar,video-generation,visionstory
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: visionstory==0.0.7
Description-Content-Type: text/markdown

# VisionStory CLI

Command-line interface for the [VisionStory API](https://openapi.visionstory.ai/docs) — generate media, clone voices, synthesize speech, transcribe audio, create subtitles, and align scripts from your terminal.

- **Covers the whole API** — every list, create, query, and delete operation has a subcommand.
- **JSON in, JSON out** — prints the API response to stdout; composes with `jq` and shell scripts.
- Thin wrapper over the [`visionstory`](https://pypi.org/project/visionstory/) SDK — same auth, same API.

## Install

```bash
pip install visionstory-cli
```

This installs the `visionstory` command (and pulls in the `visionstory` SDK). For the Python library on its own, install [`visionstory`](https://pypi.org/project/visionstory/); for the MCP server, [`visionstory-mcp`](https://pypi.org/project/visionstory-mcp/).

## Quick start

```bash
export VISIONSTORY_API_KEY="sk-vs-xxxxxxxxxxxxxxxxxxx"

visionstory avatars
visionstory voices
visionstory create-video --avatar-id 4321918387609092991 --text "Hello from VisionStory." --voice-id Alice --output result.mp4
visionstory status --video-id 7241059991822401536
```

The API key is read from `VISIONSTORY_API_KEY` and never passed as a flag. `create-video` and `create-ai-video` block until the video is ready and download it with `--output`; add `--no-wait` to return immediately.

## Commands

```bash
# Discover
visionstory --version
visionstory update --check
visionstory doctor
visionstory contract
visionstory models | avatars | voices | credits | videos | assets

# Talking-avatar video
visionstory create-video --avatar-id <id> --text "..." --voice-id Alice --output result.mp4
visionstory status --video-id <id>

# Avatars / voices / assets
visionstory create-avatar --image-url <url>
visionstory clone-voice --audio-url <url>
visionstory upload-asset --url <url>

# Text-to-speech, audio understanding, image, AI (Seedance) video
visionstory tts --text "..." --voice-id Alice --locale en-GB --output speech.mp3
visionstory transcribe --audio-file interview.mp3 --diarize --srt --output interview.srt
visionstory align --audio-url https://example.com/speech.mp3 --text "..."
visionstory create-image --model-id <model> --prompt "..."
visionstory ai-video-cost --model-id seedance-2.0 --duration-sec 8
visionstory create-ai-video --model-id seedance-2.0 --prompt "..." --output ai.mp4

# Delete
visionstory delete-video --video-id <id>
```

Run `visionstory --help` or `visionstory <command> --help` for every command and flag. Full guide: <https://openapi.visionstory.ai/docs/guides/cli>.

## Manage the installation

```bash
visionstory --version       # installed version, human-readable
visionstory version         # installed version as JSON
visionstory update --check  # compare with the latest PyPI release
visionstory update          # upgrade through uv tool or pip
visionstory doctor          # local setup diagnostics; never prints the API key
visionstory uninstall       # asks before removing the CLI
```

Interactive commands also check the shared release manifest at most once per day. A newer release is announced on stderr at most once per week with its upgrade command and release notes, so JSON stdout stays safe for scripts. Checks fail silently offline and never install updates automatically. Set `VISIONSTORY_UPDATE_CHECK=0` to disable passive notices.

`visionstory upgrade` is an alias for `visionstory update`. For an unattended uninstall, use
`visionstory uninstall --yes`.

`visionstory contract` requires no API key and prints the OpenAPI contract version, SHA-256
fingerprint, and operation count shared by the SDK and MCP package.

## License

MIT
