syncast-cli

Syncast CLI — AI image/video/audio generation and agent integration for Syncast.

Installation

npm install -g syncast-cli
# provides both `syncast` and `syncast-cli` commands

Quick start

# 1. Log in (device authorization in browser)
syncast auth login

# 2. Verify
syncast auth status

# 3. Generate an image
syncast imagine --prompt "a cat on the moon" --model nano-banana-pro

# Generate with a local reference image
syncast imagine -p "turn this into a studio product photo" --reference-image ./reference.png

# Generate a custom-size image, e.g. 4x6 inch at 600 DPI
syncast imagine -p "passport photo" --model seedream-5-0 --resolution custom --width 2400 --height 3600

# 4. Generate a video
syncast video --prompt "ocean waves at sunset" --model veo-3-1

# 5. Generate a sound effect
syncast sound-effect --prompt "distant muffled thunder, low deep rumbling, intermittent thunderclaps, no voices, no music"

Commands

| Command | Description | |---------|-------------| | syncast auth login | Device authorization login | | syncast auth status | Check session | | syncast auth logout | Clear local session | | syncast imagine | Image generation | | syncast video | Video generation | | syncast sound-effect / syncast sfx | Sound effect generation | | syncast task status <id> | Task status / SSE stream | | syncast task cancel <id> | Cancel task | | syncast project-agent serve | Local bridge for external agents operating an opened frontend project | | syncast project-agent run <action> | Forward a Syncast Agent Action into the connected project page | | syncast project-agent wait --ref <json> | Wait for a frontend Agent Action task ref | | syncast sync / start | Local file sync (legacy) |

Project Agent bridge

project-agent is separate from the normal cloud generation commands. It is a thin transport into an already opened Syncast frontend project page. External agents should still read .agents/skills/syncast-agent-actions to decide which action to call and what JSON input to send.

Start the local bridge:

syncast project-agent serve

The command prints activation query parameters. Open or reload the Syncast project URL with those parameters once:

syncastAgentBridgeToken=...
syncastAgentBridgePort=23457

Then verify the page is connected and call actions:

syncast project-agent pages
syncast project-agent capabilities
syncast project-agent run syncast.project.inspect --input '{"limit":20}'
syncast project-agent run syncast.agent.delegate --input '{"goal":"整理项目方案","wait":false}'
syncast project-agent wait --ref '{"kind":"agent_chat","projectId":"..."}' --return-result

The bridge does not expose arbitrary browser JavaScript or UI automation. It only forwards structured requests to window.__syncastAgent in the registered project page.

Output format

Default: JSON (agent-friendly). Use --format human for readable text.

syncast imagine -p "hello" --format human

Generation defaults

Syncast's default image model is nano-banana-2. Text-to-image, reference-image generation, and ordinary image editing should all be treated as the same image input capability family: use the image-input fields supported by the current schema instead of splitting "reference" and "edit" into separate model families. Use oai-gpt-image-2 when a task explicitly needs OpenAI/GPT Image 2, mask editing, official API behavior, or strict output controls.

Direct syncast imagine supports schema passthrough:

# Merge arbitrary image input fields into task_request.input
syncast imagine -p "poster layout" --input '{"references":[{"asset_id":"ref1","remote_filename":"uploads/ref.png","reference_type":"image"}]}'

# Read the same passthrough object from a file
syncast imagine -p "poster layout" --input-file ./input.json

# Reuse an existing remote file without uploading again
syncast imagine -p "restyle this" --reference-remote uploads/ref.png

Syncast's default video model family is KittyVibe Seedance 2.0. Use kittyvibe-seedance2.0pro for normal text-to-video, image-to-video, and multi-reference/multimodal video; use kittyvibe-seedance2.0fast for fast/low-cost previews; use Global variants for complex action or high-motion scenes. Do not switch to other video models only because the user provides images or asks for references.

The Agent skill is the operational guide for agents. When the CLI exposes machine-readable generation schema, agents should use it as the source of truth for supported media-input fields and examples.

Configuration

• File: ~/.syncast/config.json
• Env: SYNCAST_API_URL or API_URL (default http://localhost:8901)

Agent / Cursor skill

See .agents/skills/syncast-cli/SKILL.md for agent installation instructions.

The CLI package and Agent skills are updated separately. Before using syncast project-agent, refresh the project skill from the published skill repo if it is missing or stale:

npx skills add latentcat/syncast-skills --skill syncast-agent-actions -y

Example prompt for agents:

Help me install Syncast CLI and log in, then generate a test sound effect.

Development

bun install
bun run build
node dist/cli.js --help

License

MIT