Metadata-Version: 2.4
Name: vcursor-cli
Version: 1.0.18
Summary: VCursor SDK & CLI - Generate videos from text, images, and URLs using AI
Author-email: Julius <support@vcursor.com>
License: MIT
Project-URL: Homepage, https://cli.vcursor.com
Project-URL: Repository, https://github.com/JThh/vcursor
Project-URL: Documentation, https://cli.vcursor.com/docs
Keywords: video,ai,generation,cli,vcursor,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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 :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.25.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"

# VCursor Python SDK & CLI

Generate videos from text, images, and URLs using AI.

## Installation

```bash
pip install vcursor-cli
```

## Quick Start

### As a library (embedded in code)

```python
from vcursor import VCursor

client = VCursor(api_key="vk-...")

# Submit a video generation task
resp = client.submit("a cat playing piano in a jazz club")

# Wait for completion with progress callback
result = client.wait_for_completion(
    resp.task_id,
    on_progress=lambda p: print(f"{p.data.progress}%")
)

print(result.data.products.url)
```

### Async usage

```python
import asyncio
from vcursor import VCursorAsync

async def main():
    async with VCursorAsync(api_key="vk-...") as client:
        resp = await client.submit("sunset timelapse over mountains")
        result = await client.wait_for_completion(resp.task_id)
        print(result.data.products.url)

asyncio.run(main())
```

### Concurrency limiting

The server enforces per-user rate limits based on subscription tier:

| Tier | Standard Requests | Agent Requests | Window    |
|------|-------------------|----------------|-----------|
| Free | 3                 | 1              | Lifetime  |
| Pro  | 30/hr             | 5/hr           | Rolling 1h|
| Plus | 120/hr            | 15/hr          | Rolling 1h|

```python
# Check current rate limit status
status = client.check_concurrency("standard")
print(f"Standard: {status.summary['standard'].used}/{status.summary['standard'].limit}")
print(f"Agent:    {status.summary['agent'].used}/{status.summary['agent'].limit}")

# Client-side limit (capped at server limit)
client = VCursor(api_key="vk-...", max_concurrency=10)
```

### As a CLI

```bash
# Authenticate
vcursor login

# Generate a video
vcursor generate "a cat playing piano"

# Agent mode
vcursor generate --agent "create a 30s commercial"

# Check concurrency status
vcursor concurrency

# With concurrency limit
vcursor generate --max-concurrency 2 "sunset timelapse"
```

## API Reference

### `VCursor` / `VCursorAsync`

| Method                    | Description                            |
|---------------------------|----------------------------------------|
| `submit(prompt, **kw)`   | Submit a standard video generation task |
| `get_progress(task_id)`  | Get task progress                      |
| `wait_for_completion()`  | Poll until task completes              |
| `cancel_task(task_id)`   | Cancel a running task                  |
| `submit_agent(message)`  | Submit an agent mode task              |
| `get_agent_progress()`   | Get agent task progress                |
| `wait_for_agent_completion()` | Poll until agent task completes   |
| `check_concurrency()`    | Check concurrency limit status         |

## Configuration

Config is stored in `~/.vcursor/config.json` (shared with the Node.js CLI).

Environment variables:
- `VCURSOR_API_KEY` - API key
- `VCURSOR_SERVER` - Server URL

## License

MIT
