How to use Model Studio CLI-Alibaba Cloud Model Studio(Model Studio)-阿里云帮助中心

Alibaba Cloud Model Studio CLI is a command-line tool built by Alibaba Cloud Model Studio specifically for AI Agents. With a single installation command and authentication setup, you can integrate the AI capabilities of Model Studio into various AI tools.

Installation and setup

Installation

Note

Prerequisites: Node.js ≥ 22.12.0. Model Studio CLI can only be installed via npm.

Option 1: Install within an AI Agent (recommended)

Tell the Agent:

Please read https://bailian.aliyun.com/cli/install.md and install Alibaba Cloud Model Studio CLI for me following the instructions

Option 2: Manual installation

# Step 1: Install CLI
npm install -g bailian-cli

# Step 2: Install Skills (register Model Studio capability descriptions to each Agent's Skills directory)
npx skills add modelstudioai/cli --all -g

# Step 3: Verify installation
bl --version

Authentication and configuration

Before using Model Studio CLI, you must complete authentication. The following authentication methods are supported:

Authentication method	Command	Use case
Console login (recommended)	`bl auth login --console`	Model invocation + application management (opens browser for OAuth login)
API Key	`bl auth login --api-key sk-xxx` (Get API Key)	Model invocation (text, image, video, speech, etc.)
Environment variable	Configure API Key environment variable	CI/CD, headless environments
Config file	`bl config set --key api_key --value sk-xxx`	Persistent (does not validate Key)
One-time pass-through	`bl text chat --api-key sk-xxx --message "Hello"`	Single invocation, not persisted

Console login and API Key can be configured simultaneously without overriding each other.

After authentication is complete, you can use bl config to configure parameters such as the model and output directory:

# View current configuration
bl config show

# Set default text model
bl config set --key default-text-model --value qwen3.7-max

# Set output directory
bl config set --key output_dir --value ~/bailian-output

Common global parameters

Parameter	Description
`--api-key <key>`	Specify API Key (effective for this invocation only)
`--region <cn\|us\|intl>`	Switch region (default: cn)
`--base-url <url>`	Custom API endpoint
`--output <text\|json>`	Output format
`--timeout <seconds>`	Request timeout
`--quiet`	Quiet mode, reduce output
`--verbose`	Print HTTP request/response details
`--no-color`	Disable ANSI colors
`--dry-run`	Preview request without executing
`--non-interactive`	Non-interactive mode, suitable for Agents and CI/CD
`--concurrent <n>`	Number of concurrent requests (default: 1)

Model Studio CLI is compatible with mainstream AI tools and frameworks such as Claude Code, Cursor, Codex, and Qwen Code. For the complete compatibility list and integration methods, see the Model Studio CLI GitHub repository.

Real-world scenarios

E-commerce product image generation

Tell the Agent:

Generate a set of Amazon product listing images, 6 images, the product is a plain black summer men's T-shirt

The Agent automatically combines multiple commands to complete the task:

Generate 6 product listing images:

 bl image generate --prompt "Plain black summer men's T-shirt, white background, Amazon product listing style" --n 6 --out-dir ./ecommerce/

To adjust a specific image:

 bl image edit --image ./ecommerce/image_01.png --prompt "Add a model wearing the T-shirt"

To generate a product showcase video:

 bl video generate --image ./ecommerce/image_01.png --prompt "T-shirt 360-degree rotating showcase" --download tshirt-demo.mp4

News podcast generation

Tell the Agent:

Search for today's AI news, write a dialogue script, then generate an audio podcast with distinct male and female voices

The Agent executes the following steps in sequence:

Search the web for news material:

 bl search web --query "today's AI news"

Use an LLM to write a dialogue script:

 bl text chat --message "Based on the following news material, write a dialogue script..."

Generate audio for each role:

 bl speech synthesize --text "Host A: Have you heard..." --voice Ethan --out host_male.mp3
 bl speech synthesize --text "Host B: What happened?..." --voice Cherry --out host_female.mp3

Use ffmpeg to merge the audio segments into a complete podcast.

Storybook generation

Tell the Agent:

Generate a Little Red Riding Hood storybook, photorealistic version, maintain character consistency, 20 pages, 16:9 aspect ratio, output as PDF

The Agent automatically completes the workflow: generate story text for each page, create style-consistent illustrations based on the text, then lay out and export as PDF.

Command reference

Text chat

bl text chat

Send text chat requests, compatible with the OpenAI API format.

bl text chat --message <text> [flags]

Parameter	Description	Default
`--model <model>`	Model ID	qwen3.7-max
`--message <text>`	Message content (repeatable, prefix with `role:` to set role)	—
`--messages-file <path>`	Read messages from a JSON file (`-` for stdin)	—
`--system <text>`	System prompt	—
`--max-tokens <n>`	Maximum number of tokens to generate	4096
`--temperature <n>`	Sampling temperature (0.0, 2.0]	—
`--top-p <n>`	Top-p sampling threshold	—
`--stream`	Streaming output (enabled by default on TTY)	—
`--tool <json-or-path>`	Tool definition, JSON or file path (repeatable)	—
`--enable-thinking`	Enable thinking mode (for qwen3/qwq models)	—
`--thinking-budget <n>`	Maximum tokens for thinking mode	4096

Omni-modal understanding

bl omni

Omni-modal conversation supporting image, audio, and video inputs with text and speech outputs.

bl omni --message <text> [flags]

Parameter	Description	Default
`--message <text>`	Message content (repeatable)	—
`--model <model>`	Model ID	qwen3.5-omni-plus
`--system <text>`	System prompt	—
`--image <url>`	Image URL or local file (repeatable)	—
`--audio <url>`	Audio URL or local file (repeatable)	—
`--video <url>`	Video URL or local file	—
`--voice <voice>`	Output voice (options: Chelsie, Cherry, Ethan, Serena, Tina)	Cherry
`--audio-format <fmt>`	Audio output format	wav
`--audio-out <path>`	Save audio to file	Auto-generated
`--text-only`	Output text only, without generating audio	—
`--max-tokens <n>`	Maximum number of tokens to generate	—
`--temperature <n>`	Sampling temperature (0.0, 2.0]	—

Image generation and editing

bl image generate

Generate images from text.

bl image generate --prompt <text> [flags]

Parameter	Description	Default
`--prompt <text>`	Image description	—
`--model <model>`	Model ID	qwen-image-2.0
`--size <W*H>`	Image size, supports ratio (3:4, 16:9) or pixels (2048*2048)	—
`--n <count>`	Number of images to generate per request (max 6)	1
`--seed <n>`	Random seed for reproducible results	—
`--negative-prompt <text>`	Negative prompt to exclude unwanted content	—
`--prompt-extend <bool>`	Enable prompt extension	true (synchronous mode)
`--watermark <bool>`	Add watermark	true
`--no-wait`	Async mode, return task ID immediately	—
`--out-dir <dir>`	Image save directory	—
`--out-prefix <prefix>`	Filename prefix	image
`--poll-interval <seconds>`	Polling interval	3

bl image edit

Edit existing images with support for multi-image compositing.

bl image edit --image <url> --prompt <text> [flags]

Parameter	Description	Default
`--image <url>`	Source image URL or local file (repeatable, for multi-image compositing)	—
`--prompt <text>`	Editing instruction	—
`--model <model>`	Model ID	qwen-image-2.0
`--size <W*H>`	Output size	—
`--n <count>`	Number of outputs (max 6)	1
`--seed <n>`	Random seed	—
`--negative-prompt <text>`	Negative prompt	—
`--prompt-extend <bool>`	Enable prompt extension	true
`--watermark <bool>`	Add watermark	true
`--out-dir <dir>`	Save directory	—
`--out-prefix <prefix>`	Filename prefix	edited

Video generation and editing

bl video generate

Generate videos from text or images.

bl video generate --prompt <text> [--image <url>] [flags]

Parameter	Description	Default
`--prompt <text>`	Video description	—
`--model <model>`	Model ID	happyhorse-1.0-t2v (i2v when --image is specified)
`--image <url>`	Input image, enables image-to-video mode	—
`--negative-prompt <text>`	Negative prompt	—
`--resolution <res>`	Resolution (e.g. 1280*720)	—
`--ratio <ratio>`	Aspect ratio (e.g. 16:9, 1:1)	—
`--duration <seconds>`	Video duration (seconds)	5
`--prompt-extend <bool>`	Enable prompt extension	—
`--watermark <bool>`	Add watermark	true
`--seed <n>`	Random seed	—
`--download <path>`	Save to file upon completion	—
`--no-wait`	Return task ID immediately	—
`--async`	Same as --no-wait, for Agent/CI mode	—
`--poll-interval <seconds>`	Polling interval	5

bl video edit

Edit videos with support for style transfer, object replacement, and more.

bl video edit --video <url> --prompt <text> [flags]

Parameter	Description	Default
`--video <url>`	Input video URL or local file (2-10 seconds)	—
`--prompt <text>`	Editing instruction	—
`--model <model>`	Model ID	happyhorse-1.0-video-edit
`--ref-image <url>`	Reference images (up to 4, comma-separated)	—
`--negative-prompt <text>`	Negative prompt	—
`--resolution <res>`	Resolution: 720P or 1080P	1080P
`--ratio <ratio>`	Aspect ratio (16:9, 9:16, 1:1, 4:3, 3:4)	—
`--duration <seconds>`	Output duration (2-10 seconds)	—
`--audio-setting <mode>`	Audio processing: auto or origin (keep original audio)	auto
`--prompt-extend <bool>`	Enable prompt extension	—
`--watermark <bool>`	Add watermark	true
`--seed <n>`	Random seed	—
`--download <path>`	Save to file	—
`--no-wait`	Return task ID immediately	—
`--poll-interval <seconds>`	Polling interval	15

bl video ref

Generate videos from multi-image references with support for multiple subjects, camera angles, and dubbing.

bl video ref --prompt <text> --image <url>... [flags]

Parameter	Description	Default
`--prompt <text>`	Video description, use markers to reference assets (image 1, video 1, etc.)	—
`--model <model>`	Model ID	happyhorse-1.0-r2v
`--image <url>`	Reference images (repeatable, for multiple subjects)	—
`--ref-video <url>`	Reference videos (repeatable)	—
`--image-voice <url>`	Voice-over for images (matched by position)	—
`--video-voice <url>`	Voice-over for videos (matched by position)	—
`--resolution <res>`	Resolution: 720P or 1080P	720P
`--ratio <ratio>`	Aspect ratio (16:9, 9:16, 1:1)	—
`--duration <seconds>`	Video duration (2-10 seconds)	5
`--prompt-extend <bool>`	Enable prompt extension	—
`--watermark <bool>`	Add watermark	true
`--seed <n>`	Random seed	—
`--download <path>`	Save to file	—
`--no-wait`	Return task ID immediately	—
`--poll-interval <seconds>`	Polling interval	15

bl video task get

Query the status of an asynchronous video task.

bl video task get --task-id <id>

Parameter	Description
`--task-id <id>`	Async task ID

bl video download

Download a completed video by task ID.

bl video download --task-id <id> --out <path>

Parameter	Description
`--task-id <id>`	Task ID
`--out <path>`	Output file path

Visual understanding

bl vision describe

Describe image or video content using vision models.

bl vision describe --image <path-or-url> [flags]

Parameter	Description	Default
`--image <path-or-url>`	Image path or URL	—
`--video <url>`	Video file path or URL	—
`--prompt <text>`	Question about the content	Auto-detect
`--model <model>`	Vision model	qwen3-vl-plus

Speech synthesis and recognition

bl speech synthesize

Text-to-speech (TTS).

bl speech synthesize --text <text> [flags]

Parameter	Description	Default
`--text <text>`	Text to synthesize	—
`--text-file <path>`	Read text from file	—
`--model <model>`	Model ID	cosyvoice-v3-flash
`--voice <voice>`	Voice ID (use --list-voices to view available voices)	—
`--list-voices`	List available voices	—
`--format <format>`	Audio format: mp3, pcm, wav, opus	mp3
`--sample-rate <rate>`	Sample rate (Hz)	—
`--volume <volume>`	Volume (0-100)	50
`--rate <rate>`	Speech rate (0.5-2.0)	1.0
`--pitch <pitch>`	Pitch (0.5-2.0)	1.0
`--seed <seed>`	Random seed（0-65535）	—
`--language <lang>`	Language hint (zh, en, ja, ko, etc.)	—
`--instruction <text>`	Natural language style instruction (e.g., "please speak in a gentle tone")	—
`--enable-ssml`	Enable SSML markup parsing	—
`--out <path>`	Save audio to file	Auto-generated
`--stream`	Stream raw PCM audio output	—

bl speech recognize

Speech-to-text (ASR).

bl speech recognize --url <audio-url> [flags]

Parameter	Description	Default
`--url <url>`	Audio file URL or local path (repeatable, up to 100)	—
`--model <model>`	Model ID	fun-asr
`--language <lang>`	Language hint (zh, en, ja, etc.)	—
`--diarization`	Enable speaker diarization	—
`--speaker-count <n>`	Expected number of speakers (requires --diarization)	—
`--vocabulary-id <id>`	Hot word list ID to improve recognition accuracy	—
`--channel-id <n>`	Audio channel ID	0
`--out <path>`	Save full recognition results to JSON file	—
`--no-wait`	Return task ID immediately	—
`--poll-interval <seconds>`	Polling interval	2

Web search

bl search web

Web search。

bl search web --query <text> [flags]

Parameter	Description	Default
`--query <text>`	Search keywords	—
`--count <n>`	Number of search results	10
`--list-tools`	List available MCP search tools	—

Applications and data

bl app call

Call a Model Studio application (agent or workflow).

bl app call --app-id <id> --prompt <text> [flags]

Parameter	Description	Default
`--app-id <id>`	Application ID (required)	—
`--prompt <text>`	Input prompt	—
`--image <url>`	Image URL (repeatable)	—
`--file-id <id>`	Pre-uploaded file ID (repeatable)	—
`--session-id <id>`	Session ID for multi-turn conversations	—
`--stream`	Streaming output (enabled by default on TTY)	—
`--pipeline-ids <ids>`	Knowledge base pipeline ID (comma-separated)	—
`--memory-id <id>`	Memory ID to enable long-term memory	—
`--biz-params <json>`	Business parameters JSON (workflow variables)	—
`--has-thoughts`	Display Agent thinking process	—

bl app list

List Model Studio applications.

bl app list [flags]

Parameter	Description	Default
`--name <name>`	Search by name	—
`--page <n>`	Page number	1
`--page-size <n>`	Items per page	30
`--region <region>`	API region	cn-beijing

bl memory add

Add memory.

bl memory add --user-id <id> [flags]

Parameter	Description
`--user-id <id>`	User ID (required)
`--messages <json>`	Messages JSON array
`--content <text>`	Custom memory content
`--profile-schema <id>`	User profile schema ID
`--memory-library-id <id>`	Memory library ID (isolated memory space)

bl memory search

Search memory.

bl memory search --user-id <id> [flags]

Parameter	Description	Default
`--user-id <id>`	User ID (required)	—
`--query <text>`	Search keywords	—
`--messages <json>`	Messages JSON array for contextual search	—
`--top-k <n>`	Number of results to return	10
`--memory-library-id <id>`	Memory library ID	—

bl memory list

List memories.

bl memory list --user-id <id> [flags]

Parameter	Description	Default
`--user-id <id>`	User ID (required)	—
`--page-size <n>`	Items per page	10
`--page <n>`	Page number	1
`--memory-library-id <id>`	Memory library ID	—

bl knowledge retrieve

Retrieve from Model Studio knowledge base (requires AccessKey authentication).

bl knowledge retrieve --index-id <id> --query <text> [flags]

Parameter	Description	Default
`--index-id <id>`	Knowledge base index ID (required)	—
`--query <text>`	Search keywords (required)	—
`--workspace-id <id>`	Model Studio workspace ID	—
`--top-k <n>`	Number of results to return	10
`--rerank`	Enable reranking	—
`--rerank-top-n <n>`	Number of results to retain after reranking	—
`--access-key-id <key>`	Alibaba Cloud AccessKey ID	—
`--access-key-secret <key>`	Alibaba Cloud AccessKey Secret	—

Development utilities

bl file upload

Upload local files to DashScope temporary storage (valid for 48 hours).

bl file upload --file <path> --model <model>

Parameter	Description
`--file <path>`	Local file path
`--model <model>`	Target model name (file is bound to this model)

bl usage free

Query model free quota.

bl usage free --model <model> [flags]

Parameter	Description	Default
`--model <model>`	Model name	—
`--region <region>`	API region	cn-beijing

bl mcp list

List activated MCP services.

bl mcp list [flags]

Parameter	Description	Default
`--name <text>`	Filter by name	—
`--type <type>`	Service type: OFFICIAL or PRIVATE	OFFICIAL
`--page <n>`	Page number	1
`--page-size <n>`	Items per page	30
`--region <region>`	API region	cn-beijing

bl pipeline run

Run a pipeline workflow.

bl pipeline run <file> [flags]

Parameter	Description	Default
`--input <json>`	Runtime input (JSON)	—
`--input-file <path>`	Read input from file	—
`--concurrency <n>`	Maximum number of parallel steps	1
`--events <format>`	Event output format: jsonl	—
`--timeout <seconds>`	Step timeout	—

bl advisor recommend

Recommend the best model based on your requirements.

bl advisor recommend <prompt> [flags]

Parameter	Description
`--message <text>`	Describe your requirements
`--dry-run`	Show only intent analysis and candidate list without ranking

FAQ

Q: What should I do if the installation fails?

Verify that your Node.js version is 22.12.0 or later and install using npm (pnpm/yarn is not supported):

node --version
npm install -g bailian-cli
npx skills add modelstudioai/cli --all -g

Q: What should I do if authentication fails?

Check whether the API key is correctly configured:

bl auth status

To reconfigure:

bl auth logout
bl auth login --api-key sk-xxx
# Or log in through the browser
bl auth login --console

Q: Can I use local files directly?

Yes. Simply pass the file path to the Agent. The CLI automatically uploads files to temporary storage (valid for 48 hours):

Convert ./photo.png to watercolor style
Transcribe the recording ./meeting.wav
Describe the content of ./demo.mp4

Q: How do I view the full parameters of a command?

Ask the Agent "What parameters does bl image generate have?", or run the following command directly:

bl <command> --help