This command installs the CLI and its dependencies. It does not install a GPU model on your computer.
If your Python command is python3, use that name instead. A virtual environment can keep the installation separate.
Install from an Uncen source checkout
Run this command from the repository root:
python -m pip install -e packages/uncen-cli
The public wheel does not require access to the source repository.
2. Sign in and set a spending limit
uncen login --max-credits 100 --label "My game assets"
uncen whoami
uncen capabilities
Open the Uncen approval page when the CLI starts your browser.
Sign in with Google.
Check the requested asset permissions and credit limit.
Approve the request.
Return to the terminal.
The grant uses your existing account balance. The credit limit is a maximum, not a credit purchase.
whoami shows the account, grant, and limits. capabilities shows providers, settings, availability, and permissions.
Check capabilities before generating. A command does not enable a missing worker or substitute another provider.
Sound effects require an enabled Stable Audio 3.0 Small SFX worker. Availability can differ from other asset types.
Public Breeze TTS 2 voice design remains disabled until Uncen records written commercial authorization. A temporary admin-only evaluation path stays private and non-commercial.
Give Claude, Codex, or another coding agent a grant
The agent does not need your Google password. Run the login command on the computer where the agent works.
Open the printed approval URL yourself. The account that approves the page owns the assets and pays for them.
Use a separate profile for each grant. Global options, including --profile, go before the command.
The grant does not give the coder your account's administrator permissions.
Approve from another browser or phone
uncen login --max-credits 100 --no-browser
Open the printed approval URL in a trusted browser. Check the code and approve the request.
The CLI still requires a native credential store. Linux requires a working Secret Service or KWallet session.
Do not copy browser cookies or Google tokens into the terminal.
3. Create an asset
--out waits for the job and downloads the result. Without --out or --wait, the CLI returns the queued request.
Image
uncen generate image --prompt "A bright cartoon forest menu background" --width 1024 --height 1024 --out assets/menu.png
Use images for backgrounds, concept art, textures, or references. Check the provider's supported dimensions.
uncen generate image --prompt "Cali briefs the squad inside a carrier hangar" --reference-image assets/cali.png --out assets/cali-briefing.png
Use a local character image to keep identity and clothing consistent. See the reference image section below.
3D model
uncen generate model --prompt "One low-poly wooden supply crate with a closed lid" --geometry-profile prop --out assets/crate.glb
Use prop for simple objects. Other profiles include standard, character, and source.
Fewer vertices do not guarantee sharp edges. A character model does not automatically include a skeleton or animation.
Music
uncen generate music --prompt "Playful instrumental game music" --duration 20 --music-kind gameplay_loop --wait
Inspect download.filename and download.mime_type. Then choose the correct extension when you download the result.
Speech
uncen generate tts --text "The next round starts now." --provider PROVIDER_FROM_CAPABILITIES --voice VOICE_FROM_CAPABILITIES --wait
Replace both placeholders with a listed provider and voice. Speech uses --text, not --prompt.
Browse published Asset Yard voices with uncen voices list. Then use the stable voice key with Chatterbox:
uncen generate tts --text "All pilots, prepare for launch." --provider chatterbox --voice ayv2_hero_vanguard_c1 --out assets/launch.wav
See the TTS voice section below for catalog, built-in, and custom voices.
The output format depends on the provider.
Voice design
uncen generate voice --prompt "A calm space guide with clear diction" --text "Welcome aboard. I will guide your crew through each system check, one clear step at a time. Watch the blue status lights, confirm each green signal, and stay with me until the launch computer reports that every system is ready." --provider breeze_tts2_voice --language en --cfg-scale 4 --out assets/guide-voice.wav
This command prepares a private Chatterbox reference sample. Voice design is not an alternate speech provider.
Use 160 to 500 characters for the sample transcript.
The server returns license_pending until written approval and worker activation.
Sound effect
uncen generate sfx --prompt "One short cartoon pop, dry recording, no music" --duration 1 --set steps=8 --out assets/pop.wav
The SFX worker supports WAV output, durations from 1 to 30 seconds, and 1 to 8 sampling steps.
Describe the sound and its timing. Request a single event when you need a game action sound.
Video
uncen generate video --prompt "The camera moves around the object" --image-media-id OWNED_IMAGE_ID --duration 5 --out assets/preview.mp4
Replace OWNED_IMAGE_ID with a completed image from this CLI grant. A collection restriction also applies to source images.
The first version uses an owned reference image. It does not accept an arbitrary image URL.
Frame spacing can change the exact duration. For WAN, one second at 16 frames per second produces 17 frames.
Check metadata.duration_seconds and metadata.dimensions for measured output values. The requested settings stay unchanged.
Design a Breeze voice for Chatterbox
Public Breeze TTS 2 voice design is disabled. Approved admin grants can use the temporary private evaluation mode. Run uncen capabilities before a request.
Evaluation samples and their Chatterbox derivatives are non-commercial. Do not distribute them with a product.
The response reports enabled: false and unavailable_code: license_pending until activation.
Existing grants do not receive voice:generate automatically. Create a new profile, or revoke and replace the old grant.
First, run the voice command above. The prompt describes the voice, and the text gives the exact sample transcript.
Choose text that produces a sample from 10 to 30 seconds. Copy its completed media ID.
Then pass that private sample to Chatterbox:
uncen --profile voice-work generate tts --text "Navigation is ready. Start the launch sequence when your team is prepared." --provider chatterbox --voice custom --reference-media-id VOICE_MEDIA_ID --out assets/launch-guide.wav
Replace VOICE_MEDIA_ID with the first command's media ID.
The server accepts an owned private media ID. It does not accept a local path or arbitrary URL.
Optional steering also uses an owned audio media ID and its exact transcript:
uncen --profile voice-work generate voice --prompt "Keep the pace, but sound warmer and less formal" --text "You found the hidden route. Stay close, and I will get everyone home safely. Follow the painted stones beside the river, keep your lantern covered, and wait for my signal before the whole group crosses the old wooden bridge." --provider breeze_tts2_voice --steering-media-id OWNED_AUDIO_MEDIA_ID --steering-text "The exact transcript spoken in the steering audio." --out assets/warm-guide-voice.wav
Use --steering-media-id and --steering-text together.
Run both stages separately. Manifest version 1 cannot pass a new media ID to a later entry.
A later manifest can use a literal reference_media_id after the voice sample exists.
Use --provider to select a listed provider. Use --set KEY=VALUE for exact settings from capabilities.
--max-credits 5 adds a limit for one request. The grant limit and account balance still apply.
Music and sound-effect generation do not guarantee seamless loops. Inspect the audio before adding it to a game.
Seeds do not guarantee identical files across runs or hardware. Reuse downloaded files when you need an exact match.
4. Keep a character consistent with reference images
Pass a local character image with --reference-image. Repeat the option when the editor supports several references.
uncen --profile claude-game generate image --collection dangerous --prompt "Cali gives a mission briefing on the carrier bridge. Keep her face, hair, uniform, and insignia consistent." --reference-image references/cali.png --out assets/cali-bridge-briefing.png
uncen --profile claude-game generate image --collection dangerous --prompt "Cali and the commander study a tactical display. Preserve both identities." --reference-image references/cali.png --reference-image references/commander.png --out assets/tactical-briefing.png
The CLI accepts PNG, JPEG, and WebP files up to 20 MiB. Local files and media IDs share one five-image limit.
A provider can set a lower limit. Check image.reference_providers in uncen capabilities.
The CLI calculates each file's SHA256 value. The server reuses a matching private upload in the same account and collection.
Use an existing owned image when you already know its media ID:
uncen --profile claude-game generate image --collection dangerous --prompt "Cali reports from a damaged flight deck." --reference-image-media-id OWNED_IMAGE_ID --out assets/cali-flight-deck.png
You can mix both options. The CLI rejects duplicate or invalid media IDs.
The server checks the image owner, state, file type, and collection before dispatch.
The API does not accept an arbitrary image URL. This rule prevents a cross-account read.
The generated image remains in the account's media library and private storage. The CLI also downloads the requested local file.
A manifest cannot contain a local reference path. Use settings.reference_image_media_ids after the upload exists.
5. Choose a TTS voice
Each published Asset Yard voice has a stable, unique voice_key. A game can store this key without storing audio locations.
You do not need to remember the keys. Search the catalog by category or name:
uncen --profile claude-game voices list
uncen --profile claude-game voices list --category game_hero --search vanguard
uncen --profile claude-game voices list --limit 200 --offset 0
uncen --profile claude-game voices show ayv2_hero_vanguard_c1
The key format is stable and readable. For example, ayv2_hero_vanguard_c1 identifies candidate one for the Hero Vanguard design.
Use the returned key directly:
uncen --profile claude-game generate tts --collection dangerous --text "All pilots, prepare for launch." --provider chatterbox --voice ayv2_hero_vanguard_c1 --out assets/launch.wav
Voice mode
Selection
Use
Asset Yard catalog
A stable voice_key from uncen voices list
Reusable game characters and narrators
Provider voice
A provider and voice from tts.providers in uncen capabilities
A Breeze evaluation sample until commercial authorization
A provider voice is optional. The provider uses its default voice when you omit --voice.
uncen voices list returns 100 items by default. Use --limit and --offset for a larger catalog.
uncen capabilities lists only voices that the active worker can use. A key appears there after an explicit publication.
A published bank preset binds its private S3 URI to the verified audio SHA-256. The worker checks these bytes before ComfyUI receives them.
Catalog results include release_basis and human_reviewed. A human_review release passed the score gate. A technical_checks release passed batch, trait receipt, storage, format, and loudness checks only.
A custom reference must be a ready Breeze sample from the same client, grant, and collection. It must last 10 to 30 seconds.
Operator review is the standard release path. Open uncen.ai/admin/voice-bank with an administrator account.
The current bank has 140 designs and two candidates for each design.
Each v2 design records requested presentation, age, accent, timbre, and delivery. The API returns the exact creator prompt and a verified receipt status.
Observed presentation and age describe the generated audio. They stay separate from the requested creator targets.
Each player uses a normalized review copy by default. Expand the original player to compare the pristine generation.
The final review copy measures from -19.0 through -17.5 LUFS. Its true peak does not exceed -1.4 dBTP.
Filter by batch, category, review status, or text. Listen to each candidate and score all five quality fields.
Select the observed voice presentation and age. These traits describe the sound, not a biological identity.
Approval needs a 4.0 average. Intelligibility and audio quality must each score at least 4.
Needs work keeps a candidate pending. Reject prevents publication.
Review status does not change the live catalog. Publication creates the explicit runtime set.
Click Publish approved after review. Restart the Chatterbox worker after publication.
An admin can use Technical release all for urgent internal use. Every planned candidate must remain unreviewed and pass all technical checks.
A technical release does not create scores or observed traits. Check release_basis and human_reviewed in CLI results.
A published profile cannot receive a review. Depublish it or create a new candidate revision before human review.
VoxCPM2 generates the private bank. It is not a public generate voice provider.
6. Give this brief to a coding agent
Give the agent this page and the following text. Replace PROJECT_SLUG with one stable project name.
Follow https://multiplayers.ai/help/asset-cli as the canonical Asset Yard CLI guide.
Install the published wheel before you start.
Place --profile claude-game before each command.
Ask me to open and approve the login URL. Never ask for my Google password.
Run whoami and capabilities before you create an asset.
Use --collection PROJECT_SLUG on every request.
Use --reference-image for a local character reference.
Reuse an owned image with --reference-image-media-id when its media ID is known.
Run voices list and select a stable voice_key for each speaking character.
Use --provider chatterbox and that voice_key for TTS.
Use --out for every final asset.
Keep request IDs and asset lock files. Resume a request instead of generating a duplicate.
Do not place CLI tokens in source files, prompts, logs, or the repository.
The human approves the grant. The agent receives a scoped CLI credential, not the Google session.
7. Build a repeatable asset pack
Create an assets.yaml file in your game directory:
version: 1
assets:
- id: crate
kind: model
prompt: One low-poly wooden supply crate with a closed lid
settings:
geometry_profile: prop
out: assets/crate.glb
- id: pop
kind: sfx
prompt: One short cartoon pop, dry recording, no music
settings:
duration_seconds: 1
seed: 42
out: assets/pop.wav
The CLI creates assets.coder-a.lock.json. Run the same command to resume the pack.
The lock keeps request IDs, actual settings, metadata, file hashes, and credit usage. It also binds the pack to its account and grant.
Builds run sequentially and give each new request only the remaining budget.
Previously generated assets still count toward the same lock's budget.
Changing a locked prompt or settings produces an error.
Use a new asset ID, run, or lock file when you want a new generation.
Use --output-dir when a run needs a separate output directory.
Collections are optional. Add --collection my-game to organize a pack without creating a Multiplayers project.
For coding comparisons, give each coder the same completed pack. For generation comparisons, use separate runs and budgets.
Manifest path rules
Output paths use forward slashes and stay beneath the manifest directory or the explicit output directory.
Absolute paths, traversal, symbolic links, and duplicate paths are errors.
Keep the JSON lock file for reproducible assets. Add *.uncen-lock to the game's ignore file.
JSON manifests use the same schema as YAML manifests.
8. Resume or download a job
The CLI records a request UUID before it submits the job. Keep that UUID when a command times out or loses its connection.
uncen jobs status REQUEST_UUID
uncen jobs wait REQUEST_UUID --timeout 1800
uncen jobs download REQUEST_UUID --out assets/recovered.glb
Replace REQUEST_UUID with the actual request ID. Choose an output path that matches the returned file format.
Stopping the CLI does not cancel the server job. A new generate command creates another request unless you reuse its exact request ID.
For an asset pack, repeat the original assets build command. The lock preserves unfinished requests.
Keep the same login grant while resuming jobs. Token refresh preserves the grant, but a new login creates another grant.
The CLI rejects a different grant instead of resubmitting an old request and charging again. Downloaded files remain usable after logout.
Files, credentials, and server storage
Item
Where it stays
Downloaded assets
Normal files in your local game directory. The game does not need an Uncen token at runtime.
Generation records and files
Your Uncen account, the media database, and S3. Downloading does not delete the server copy.
Asset manifest and JSON lock
Your project directory. They contain prompts and metadata, but no credentials or signed download URLs.
Access and refresh tokens
The operating system credential store. The CLI does not print these tokens.
Request journals
The operating system state directory, or the directory selected with --state-dir.
The first version does not provide temporary retention or delete-on-download. Read each asset's license metadata before distributing it.
New CLI outputs are private. Website previews require your account login. Upload an edited copy when you need a separate version.
Downloads verify SHA256 and byte counts before publishing the local file. An identical file is reused.
A different local file requires another path or explicit --overwrite. The CLI does not silently replace edited game assets.
Troubleshooting and automation
The command cannot find a credential store
Windows uses Credential Manager. macOS uses Keychain. Linux requires Secret Service or KWallet.
The CLI refuses plaintext credential backends. Configure the native store before login.
For CI, explicitly provide a scoped access token through a secret manager:
uncen --token-env UNCEN_ASSET_TOKEN whoami
Environment tokens do not refresh. Never put tokens in source files, manifest files, or command arguments.
A provider or asset type is unavailable
Run uncen capabilities. Check both availability and authorization for that asset type.
An unavailable worker requires server configuration. A missing permission requires a grant with that permission.
The CLI does not choose another model or paid service without your request.
A refresh response was lost
The client stops instead of reusing a rotated refresh token.
uncen logout
uncen login --max-credits 100
This creates a new grant. Existing remote requests remain associated with the original grant.
Use existing downloaded files. Do not start replacement generations unless you intend to spend credits again.
Use the CLI from an agent or script
Normal results and errors use one JSON object on stdout. Progress and approval information use stderr.
--json is accepted, but JSON output is already the default. Read the exit code and preserve the returned request ID.
0 Command succeeded
2 Invalid input or budget
3 Login, permission, or credential store error
4 Generation failed
5 API, network, or integrity error
6 Local file conflict or file access error
7 Wait timed out; the server job can continue
130 Command interrupted
jobs status returns a failed job as data. jobs wait returns exit code 4 for the same failed job.
🔄 Flow Configuration
Loading flow configuration...
Loading flow configuration...
🔄 Flow Progress
Flow Status
Running
Starting flow...
❌ Flow Error
✅ Flow Completed
Your content has been generated successfully!
Approve Rough SMV Cost
This is a rough estimate based on your requested runtime and current providers. The SMV planner prioritizes quality first, so final runtime and credits can land outside this range.