vidmuse

---
name: vidmuse
description: Use when an AI agent needs to work with VidMuse projects, account state, subscription credits, video/audio/image/text/tool models, generated or uploaded assets, style library entries, voice library entries, generation parameters, threads, messages, or long-term memory. Installs and uses the `vidmuse` command runtime when needed.
---

# VidMuse Skill

Use this skill when a task asks for VidMuse account state, subscription plan, model discovery, assets, style library entries, voice library entries, generation params, thread/message operations, or long-term memory operations. Treat the `vidmuse` command as the runtime for accessing VidMuse capabilities; keep user-facing answers focused on the VidMuse task unless the user asks about the command itself.

## Workflow

1. Ensure the `vidmuse` command runtime exists.

   macOS, Linux, WSL, or Git Bash:

   ```bash
   if vidmuse_path="$(command -v vidmuse)"; then
     :
   else
     tmp="$(mktemp)"
     curl -fsSL "https://vidmuse.sandcdn.com/cli/install.sh" -o "$tmp"
     installed_path="$(VIDMUSE_CLI_VERSION="${VIDMUSE_CLI_VERSION:-latest}" bash "$tmp" | tail -n 1)"
     installed_dir="$(dirname "$installed_path")"
     case ":${PATH:-}:" in *":${installed_dir}:"*) ;; *) export PATH="${installed_dir}:${PATH:-}" ;; esac
   fi
   vidmuse --version
   ```

   Windows PowerShell:

   ```powershell
   if (-not (Get-Command vidmuse -ErrorAction SilentlyContinue)) {
       $tmp = Join-Path $env:TEMP "install-vidmuse.ps1"
       Invoke-WebRequest "https://vidmuse.sandcdn.com/cli/install.ps1" -OutFile $tmp -UseBasicParsing
       $installedPath = (& powershell -ExecutionPolicy Bypass -File $tmp | Select-Object -Last 1)
       $installedDir = Split-Path -Parent $installedPath
       if (($env:PATH -split [System.IO.Path]::PathSeparator) -notcontains $installedDir) {
           $env:PATH = "$installedDir$([System.IO.Path]::PathSeparator)$env:PATH"
       }
   }
   vidmuse --version
   ```

2. Authenticate when needed.

   First check whether the current session is already authenticated:

   ```bash
   vidmuse profile get --output json
   ```

   If the command returns an auth error, ask before starting any login flow because browser and device login require user action.

   Use this decision tree:

   | Environment | Command |
   |---|---|
   | Local desktop with browser access | `vidmuse login` |
   | Headless or remote terminal with streaming output | `vidmuse login --device` |
   | Agent shell cannot keep a long-running command visible | `vidmuse login --device --start`, show the URL/code to the user, then run `vidmuse login --device --complete` after the user confirms authorization |

3. For command routing, read `references/command-map.md`.

## Local media runtime

The released CLI binary does not require Go. Account, model, asset, style, voice, thread, message, and memory commands require only the `vidmuse` binary and network access. Check extra tools before using local preview or rendering commands:

```bash
node --version
ffmpeg -version
```

| Command | Required runtime |
| --- | --- |
| `vidmuse serve` | FFmpeg only when video thumbnails are requested |
| `vidmuse render` | Node.js 22+ and FFmpeg |

When Node.js or FFmpeg is missing, do not install system packages without the user's approval. Tell the user which prerequisite is missing and offer the appropriate command:

```bash
# macOS (Homebrew)
brew install node ffmpeg

# Debian or Ubuntu
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs ffmpeg
```

The render command uses `npx --yes hyperframes@0.7.26` when no `HYPERFRAMES_BIN` is supplied. The first such render needs npm network access. Use `NODE_BIN`, `FFMPEG_BIN`, and `HYPERFRAMES_BIN` for nonstandard executable paths.

## Output Contract

Default output mode is `text`. Add `--output json` only when structured parsing is needed. Do not add it to `vidmuse render`: its `-o`/`--output` flag specifies the rendered video file path.

Use `text` for compact plain-language responses. Nested lists and maps are rendered as indented blocks.

Use `table` only for short human-facing summaries because top-level structs, maps, lists, and lists of maps are rendered as tables when possible, while nested lists and maps stay compact inside table cells.

Paginated text/table output uses a human summary such as:

```text
Showing 1-20 of 88
```

JSON output preserves structured fields such as `limit`, `offset`, `total`, and `data` when the API returns them.

Streams:

| Stream | Meaning |
|---|---|
| stdout | Command result in the selected output mode |
| stderr | Errors, verbose HTTP logs, installation logs |

Exit codes:

| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General error |
| 2 | Usage or validation error |
| 3 | Auth error: missing, expired, or invalid auth |
| 4 | Network or API error |

Error handling:

1. Check the exit code first.
2. If exit code is `0`, parse stdout only when `json` mode was requested.
3. If exit code is non-zero, show a concise error based on stderr.
4. For exit code `3`, ask the user to run `vidmuse login` or `vidmuse login --device`.
5. For exit code `4`, mention the network or API failure and retry only when the operation is read-only or explicitly safe to repeat.

## Safety

Read-only commands may be run directly when the user asks for information. Mutating commands such as `thread create`, `message send`, `memory create`, `memory update`, `memory append`, `memory push`, and `memory pop` require explicit user intent.

Never print auth tokens, cookies, or full config files in the final answer because final answers can be saved to transcripts, shared as screenshots, or copied into bug reports.