CLI Skill Guide

NadouPro CLI overview

This guide is for users and Agents using NadouPro CLI. It covers install, sign-in, model discovery, content generation, task delivery, space management, local media processing, and Canvas operations. CLI capabilities vary by version, account, and scenario. Treat nadou capability list --json, command results, and actual outputs as the source of truth.

Recommendation

After install or upgrade, run nadou version --json and nadou capability list --json first to confirm the current version and available capabilities.

Note

For write, generate, delete, or overwrite operations, follow “submit once, do not auto-retry, and query the original task when the result is uncertain.” Do not share or record cookies, tokens, Authorization headers, or other sign-in credentials.

1. Quick start

1.1 Install

Requires Node.js 16 or later. Installing from the public npm registry is recommended:

One-line install instruction: Please install NadouPro CLI: npm install -g @iqiyi-intl-nadoupro/nadou-cli. After installation, run nadou version --json to verify.

npm exec --yes --registry=https://registry.npmjs.org/ --package=@iqiyi-intl-nadoupro/nadou-cli@latest -- nadou-install
nadou version --json
nadou skill install --json
nadou skill read --json

You can also install globally:

npm install -g @iqiyi-intl-nadoupro/nadou-cli
nadou version --json

Current support: Windows x64, Linux x64/arm64, and macOS x64/arm64. npm automatically selects the matching platform dependency. If optional dependencies were disabled during install, reinstall with a normal install.

1.2 Check for updates and upgrade

nadou version --check --json
nadou update --json --no-interactive
nadou version --json

After upgrading, run nadou skill install --json again so the local Skill stays aligned with the CLI version.

1.3 Configure and sign in

Sign-in opens the international sign-in page in the system browser. Click “Continue to international sign in”, then complete international-site account sign-in using the method shown on the page. Profiles store non-sensitive settings such as space and timeouts. Sign-in sessions are stored in the local system credential store. International local configuration and sign-in sessions are stored separately; after installing the international edition, check the international sign-in status.

nadou auth login --profile <profile>
nadou auth status --profile <profile> --json
nadou auth whoami --profile <profile> --json

Replace <profile> with the Profile name actually used on this machine. If you use the default Profile, you may omit this parameter as prompted by the CLI. Do not manually copy, paste, or record cookies, tokens, or Authorization values.

1.4 Checks before Agent use

An Agent session may use a different PATH, config directory, or system credential store from a regular terminal. If you see “command not found,” “config unreadable,” or “identity verification failed,” restart the Agent first, then run:

1. nadou version --json

2. nadou auth status --profile <profile> --json

3. nadou auth whoami --profile <profile> --json

Re-sign in only after you have confirmed that the sign-in state is actually invalid.

2. Capability overview and shared conventions

2.1 Command surface

Domain	Main commands	Purpose
System and Skill	version, update, config, doctor, skill, capability	Version, configuration, diagnostics, Skill sync, and capability discovery
Identity and spaces	auth, points, space	Sign-in, points, spaces, directories, and delivery targets
Models and generation	model, text, image, video, material	Model discovery, text/image/video tasks, and asset management
Tasks and delivery	task, schedule, evidence	Estimate, submit, observe, download, scheduling, reports, and acceptance evidence
Canvas	canvas	Canvas, Graph, nodes, edges, Timeline, and final-cut export
Local media	media	Process local files; this does not replace server-side generation tasks

Treat nadou capability list --json as the source of truth for the full command set and current open range. For a single capability, use nadou capability describe <command> --json to inspect purpose, limits, async behavior, and sample commands.

2.2 Output and global flags

All commands support stable --json output. Long-running observation, event streams, and recursive directory contents can use --jsonl. Common global flags include --profile, --timeout, --trace-id, --no-interactive, and --yes.

• --json: Returns structured results suitable for programmatic handling.

• --jsonl: Outputs events or recursive results line by line, which is useful for continuous observation.

• --no-interactive: Disables interactive prompts. It does not mean cost confirmation.

• --yes: Confirms destructive operations such as delete or overwrite. It does not mean cost authorization.

• --trace-id: Used to correlate troubleshooting information for one workflow. It is not a task ID or an idempotency key.

2.3 Profile, space, and project boundaries

A Profile stores non-sensitive settings such as environment, gateway address, timeouts, auth mode, default space, and default models. Space, model, and Canvas contexts must be discovered and selected separately. Switching spaces does not implicitly create or restore other project bindings.

2.4 Scenario routing

Scenario	Recommended carrier	Execution notes
A single text, image, video, or other atomic capability	Atomic task	Confirm parameters, target space, permissions, and estimated cost before submit.
Multiple assets, multiple stages, character consistency, MV, ads, or short films	Target space/directory + Canvas	Confirm account, space, and directory first. Finish the script or storyboard before entering high-cost stages.
Modify an existing Canvas	Read and modify the original Canvas	Read the live canvas before writing, then reread after writing. Confirm first when overwriting, deleting, or hitting a conflict.
Scheduled generation	The scheduling modes currently opened by the CLI	Confirm time, timezone, account, space, and estimated cost before creating.

When the user clearly mentions NadouPro, text, image, video, assets, spaces, canvas, nodes, reference images, first/last frames, and similar scenarios, prefer the Nadou Skill. If the current CLI does not support a capability, say so clearly. Do not substitute a similar capability.

3. Model discovery and content generation

3.1 Discover models and scenarios first

nadou model list --type image --json
nadou model list --type video --json
nadou model family "<model display name>" --json
nadou model scenarios "<model-id>" --json
nadou model get <model-id> --json
nadou model schema <model-id> --json
nadou model use image <image-model> --profile <profile>
nadou model use video <video-model> --profile <profile>

Model display names, parameters, and available scenarios come from the server catalog. Do not guess model names in an Agent or script. Read the scenario or schema first, then submit matching parameters.

3.2 Generation capabilities and scenarios

Command	Common scenarios	Key inputs
nadou text	text2text, image_to_text	Prompt, optional HTTPS reference image
nadou image	text2img, image_ref, panorama, three_view, inpaint	Prompt, reference images, mask, aspect ratio, resolution, count
nadou video	text2video, first_last_frame, multi_reference, video_edit, motion_control	Prompt, duration, aspect ratio, resolution, reference video/image/audio

Prompts can be provided with --prompt, --prompt-file, or --stdin. The maximum size is 1 MiB and the content must be valid UTF-8. When an Agent uses --json, --jsonl, or --no-interactive, it should specify the prompt source explicitly. After preview and cost confirmation, official generation requires --submit. Whether positional arguments apply depends on the command help. --dry-run only constructs and validates the request; it does not submit a task. Image and video commands submit without waiting by default. Use --wait to observe completion in the same command.

The current CLI has no independent AI audio generation command. Video tasks may use reference audio, audio settings, or keep-original-audio parameters by scenario, but that is not the same as independent audio generation.

3.3 Cost, confirmation, and delivery

Cost confirmation

For tasks that may incur cost, follow “dry-run → query points → estimate → explain estimated consumption and confirm → official submit.” If the balance is empty, unlimited, or temporarily unavailable, you still must not skip estimate, budget explanation, and final confirmation.

The corresponding commands are usually nadou points summary, nadou task estimate, and nadou task submit. An estimate does not lock the final price. Confirm again against the actual returned result before submit.

Independent image/video generation and artifact delivery are two stages. The default delivery target is the personal root directory. Team spaces, directories, and copy/transfer policies must be specified explicitly. The CLI does not download artifacts by default, and does not run local media processing by default.

4. Tasks, schedules, delivery, and evidence

4.1 Task lifecycle

Common commands include task estimate, task submit, task status, task wait, task events, task outputs, task report, task history, task download, task download-batch, and task terminate.

task events can be used for continuous observation. Batch download uses a resumable manifest, which is suitable for long tasks or multi-artifact delivery. Write submissions are not retried automatically. If the process is interrupted, the network times out, or the response cannot be parsed, query the original task, request, or status record first. Do not create a new submission to retry.

4.2 Scheduled tasks

Mode	Typical use	Main limits
server	Image/video or some Canvas node generation	Does not promise general text scheduling, plan management, or DAG orchestration.
local	Ordinary image/video and independent text generation	Does not include Canvas, project context, or external reference URLs.

Scheduling requires an explicit choice of disabled, local, or server, and an IANA timezone. Confirm time, timezone, account, space, and estimated cost before creating, then choose the mode according to the current capability.

Example: nadou schedule create --body-file request.json --scheduled-at <time> --timezone <iana-timezone> --max-points <confirmed points cap>. Supported range depends on the command result.

4.3 Spaces, directories, and materials

• space current/list/use: View and switch spaces.

• space directory create/list/contents: Manage directories and view contents. Recursive contents can use --recursive --jsonl.

• space file rename: Rename a file explicitly.

• space artifact deliver: Copy or transfer trusted task artifacts to a target space or directory.

• material upload: Upload local materials, with chunked upload and optional watermark parameters.

• material delete: Delete materials. Permanent deletion requires explicit --permanent and confirmation.

Uploading a material is not the same as delivering a task artifact, and it does not automatically create a Canvas node.

4.4 Acceptance evidence

evidence generation can generate versioned local evidence from a known task ID. evidence delivery can combine a download manifest, media files, technical validation results, and human confirmation into delivery evidence. evidence validate only validates evidence structure, paths, hashes, and references. It does not trigger retry, download, delivery, or Canvas writes.

Passing technical validation is not the same as creative quality review. For official delivery, keep versions, task IDs, redacted request IDs, artifact hashes, media check results, and necessary human confirmation. Do not store tokens, cookies, or full Authorization values.

4.5 Agent interaction, artifact presentation, and recovery

Before submit, if the account, space, directory, or Canvas is not unique, first explain the options and the expected save location. If model parameters, first/last-frame roles, or batch scale are unclear, complete that information first. For batch, high-cost, delete, overwrite, move, or collaboration-conflict operations, explain the impact and get confirmation first.

• Images: State the actual count, and return each real artifact and its space path.

• Video or other media: Return the real playback/download entry and space path. A task page or thumbnail cannot replace the final artifact.

• Text: Present the body directly. If it was not saved to a space, explain why.

• Complex Canvas: Present the final artifacts, space paths, Canvas name, and real entry points, and distinguish completed stages from unfinished ones.

• Partial success: Deliver successful items first, then list failed items and redo options separately. Do not disguise the whole order as a complete success or a complete failure.

Delivery notes

Space paths and real artifact entry points are part of the delivery information. If there is no real server-side return value, or download has not finished, do not call a local path, task page, or intermediate state the final artifact.

Each write or submit step runs only once. On timeout, network errors, or unparsable responses, query the original task or original operation status. Do not change the idempotency key, resubmit, or regenerate just because a result is not visible yet. If generation fails, a copyright restriction applies, or the model refuses, stop downstream steps. If the user cancels, run cancel once and verify the final status.

5. Local media processing

nadou media only processes local files. It does not call network generation services, does not modify input files, and refuses to overwrite existing outputs by default. It supports inspect, normalize, concatenate, compose, frame extraction, technical validation, subtitle processing, and audio/video muxing.

Common standard presets include landscape, portrait, and square 1080p. Typical output is MP4/H.264, yuv420p, 30 fps, AAC-LC, 48 kHz, stereo. verify is a technical check. creative_review_required in the report still means a human review is needed.

Local media processing and Canvas Timeline/final-cut export are two separate capabilities: the former processes local files; the latter reads and writes the timeline associated with a Canvas Graph and runs server-side final-cut tasks.

6. Canvas management and Graph

6.1 Operating principles

1. Read the latest state of the target canvas with canvas get.

2. Construct one write based on the current nodes, edges, and layout.

3. After writing, read again to confirm node, edge, and artifact status.

4. If you hit a lock, collaboration conflict, permission issue, or unclear result, stop further writes. Check the original operation status first and explain the impact.

The CLI validates writable fields by node type. Users only need to focus on commands, inputs, outputs, status, and error handling. You do not need to assemble service addresses, resource URLs, or task status yourself.

6.2 Common commands

Category	Commands
Lifecycle	canvas list/create/get/rename/move/delete/restore
Read	canvas get, canvas node list, canvas assets list
Graph	canvas graph mutate
Nodes	canvas node list/create/patch/delete/estimate/generate/wait
Edges	canvas edge connect/patch/delete
Timeline	canvas media timeline validate/write/read
Final cut	canvas media export prepare/submit/observe

6.3 Canvas, nodes, and assets

Use canvas list to discover currently accessible canvases, canvas get to read the live Graph, canvas node list to inspect nodes by type, and canvas assets list to inspect historical materials or artifact projections. List results should not be treated as a live snapshot before writing.

Custom media nodes should use public Canvas node commands, with supported fields such as material IDs as input. Do not forge URLs, metadata, callbacks, or task status outside the CLI. Handle canvas conflicts, locks, and partial failures according to the actual error. Do not create substitute nodes to hide the original problem.

6.4 Timeline and final cut

Validate Timeline files offline first, then choose the final-cut flow according to the current capability. Timeline write, export prepare, submit, and observe are independent operations, and each step runs only once. If a status query returns in progress, not found, or unknown, keep querying the original operation. Do not switch paths or resubmit.

Whether a real final cut can complete depends on valid Canvas nodes, Timeline, task status, and currently opened capabilities. For publish or delivery, treat actual command returns and final artifacts as the source of truth.

7. Current CLI capability boundaries

The CLI surface may change by version, account, and scenario.

A complete workflow on the product page is not necessarily opened through the CLI, such as Director Stage, full image editing and annotation, Workbench file management, the edit suite, audio-track editing, and the screenwriting assistant. The CLI already provides some image-processing commands such as image-tool upscale. Treat current command help and actual returns as the source of truth. When you need those capabilities, use the product entry points directly, and follow both the product page and the current CLI capability.

8. Troubleshooting and feedback

8.1 Common issues

• Canvas node cannot be found: Use canvas get to fetch the live Graph first, then confirm whether the canvas ID, node type, node status, and associated task are still valid.

• A generate command exits before producing a task ID: The task has not been submitted. Do not describe this as “generation failed,” and do not resubmit.

• Timeout after a task ID has already been obtained: Keep querying the original task. Do not regenerate.

• Canvas write result is unclear: Query the original operation status, confirm the final canvas state, then decide the next step.

• The Agent cannot see the terminal sign-in state: Restart the Agent first, check PATH, the config directory, and the system credential store, then run the checks in section 1.4.

8.2 Feedback template

Feedback should at least include: the command run, CLI version, operating system and architecture, model used, Canvas ID or task ID, redacted request ID/trace ID, error code, final status, and the real artifact URL.

Do not attach cookies, tokens, Authorization values, full request headers, local credentials, or other unredacted sensitive information.

8.3 FAQ

Why do I still need estimate and confirmation after dry-run?

dry-run only validates request structure and parameters. It does not mean a server-side estimate, balance check, or final submit. Cost-related tasks still require querying points, estimating, explaining the budget, getting confirmation, and performing one official submit.

How do I keep Skill aligned with the CLI?

After upgrading the CLI, run nadou skill install --json, and use nadou capability list --json to judge whether the current command is actually open. At runtime, the Agent should prefer the official Skill synced on this machine.

Why am I not seeing the final artifact?

Query the original task status and outputs first, then confirm the delivery space and directory. Do not resubmit just because an entry point is delayed, a thumbnail is temporarily missing, or one query failed.