Files
shumai/apps/cli
yiling 4fc8476b0f feat(asset-read): expose read_asset on MCP and the CLI
Enable the mcp and cli surfaces for read_asset and get_asset_render.

- MCP: add per-Operation tool extensions. The read presenter attaches up
  to 8 images (2 MB each) inline, lists image links, supports
  inlineImages: false, and tells the model to call get_asset_render when
  a render is pending. Storage keys are stripped from the result.
- CLI: generated commands can flatten object inputs into prefixed flags
  (cli.flatten) and omit fields (cli.omit); add per-command extensions.
  New `read` and `render` commands print image links, download them with
  --out, and support --no-wait with a printed `render <taskId>` hint.
- Round frame timestamps in labels to 3 decimals.
2026-10-26 15:33:37 +08:00
..

Shumai CLI

A Command Line Interface (CLI) tool for interacting with your Shumai instance.

The CLI allows you to view projects, list folder contents, create folders, upload files and directories, create new versions of existing files, and look at images, video frames, and document pages directly from the terminal.


Installation

The CLI package is bundled inside the Shumai workspace. The published npm package (@shumai-one/shumai-cli) requires Node.js 22.12 or later.

Environment Setup

Before using the CLI, you must set the following environment variables to authenticate with your Shumai instance:

# The endpoint of your Shumai API server (e.g. http://localhost:3000)
export SHUMAI_API_SERVER="http://localhost:3000"

# Your personal API Token (Generate this in the WebUI via Settings -> API Tokens tab).
# The token is shown only once when it is created, so copy it right away.
export SHUMAI_API_KEY="your-developer-api-token"

# Optional: Enable asset deletion capability (disabled by default for safety)
export SHUMAI_ALLOW_DELETE="true"

Usage

Important

For Bun Users: Since the package binary contains a #!/usr/bin/env node shebang, running shumai-cli directly will run under Node.js. If you wish to run it using Bun, prefix the command with bun run --bun (e.g., bun run --bun shumai-cli project ls).

Run shumai-cli or query specific commands:

shumai-cli <command> [arguments] [options]

Run shumai-cli --help to list all commands, and shumai-cli <command> --help for a command's arguments and options.

Global Options

  • --json: Print the raw JSON result instead of human-friendly text, for scripts and tools like jq. Example: shumai-cli ls -p <parentId> --json | jq '.data[].id'.

When the output is piped instead of shown in a terminal, tables are printed as tab-separated values without headers.

Commands

1. List Projects

List all projects you have access to. Returns the project ID, name, and its root folder ID.

shumai-cli project ls

2. List Directory Contents

List direct children (folders and files) of a parent folder. Folders are listed first.

shumai-cli ls -p <parentId>
  • Options:
    • -p, --parent <id>: The parent folder ID (required).
    • --type <type>: Only list file, folder, or all (default).
    • --first <n>: Maximum number of items to list (default and maximum: 200).
    • --after <cursor>: Continue a long listing. When more items exist, ls prints the cursor to pass here.

3. Create a New Folder

Create a new folder under a parent folder.

shumai-cli mkdir <name> -p <parentId>
  • Options:
    • -p, --parent <id>: The parent folder ID (required).

4. Upload Files or Folders

Upload a local file or folder to a target parent folder. File sizes and paths are mapped, and uploads are streamed chunk-by-chunk with a progress bar.

shumai-cli upload <localPath> -p <parentId>
  • Options:
    • -p, --parent <id>: The parent folder ID (required).

5. Create a New Version of a File

Upload a local file as a new version of an existing asset (which must be a file or a version stack). This wraps the assets into a version stack dynamically on the server.

shumai-cli create-version <localFilePath> -p <parentAssetId>
  • Options:
    • -p, --parent <id>: The parent asset ID (file or version stack) to version (required).

6. Rename an Asset

Rename an existing file or folder in Shumai.

shumai-cli rename <assetId> <newName>

7. Move Assets

Move one or more assets (files or folders) to a destination parent folder. Note that all assets to be moved must belong to the same current parent folder.

shumai-cli move <assetId...> -p <parentId>
# or using the short alias:
shumai-cli mv <assetId...> -p <parentId>
  • Options:
    • -p, --parent <id>: The destination parent folder ID (required).

8. Delete an Asset

Delete a single file or folder by moving it to the Trash bin. For safety, this command only deletes one asset at a time and requires the SHUMAI_ALLOW_DELETE="true" environment variable to be set in your environment.

shumai-cli delete <assetId>
# or using the short alias:
shumai-cli rm <assetId>

9. Read an Asset

Look at a file: an image, video frames, PDF pages, a 3D model view, or the text of a text file. Prints a summary and a link to each image (links are valid for about an hour), or the file's text.

# An image, or the 4-view overview of a 3D model
shumai-cli read <assetId>
# 5 evenly spaced frames between 0s and 30s of a video, downloaded into ./frames
shumai-cli read <assetId> --video-start 0 --video-end 30 --video-count 5 --out frames
# Pages 1 to 3 of a PDF, or the text of a text file
shumai-cli read <assetId> --doc-mode pages --doc-start-page 1 --doc-end-page 3
shumai-cli read <assetId> --doc-mode text
# A 3D model at 90°
shumai-cli read <assetId> --degree 90
  • Options:
    • --video-start <s>, --video-end <s>, --video-count <n>: Video frames to extract (up to 20).
    • --doc-mode <pages|text>, --doc-start-page <n>, --doc-end-page <n>: PDF pages to render (up to 20), or text to read a text file.
    • --degree <deg>: 3D model angle (0, 15, 30, ..., 345).
    • --annotation-id <id>: Draw a comment's markup on the image, frame, or page.
    • -o, --out <dir>: Download the images into a folder and print their paths. With --json, each image also gets a path.
    • --max-wait-seconds <s>, --no-wait: Rendering frames or pages can take a while. read waits up to 2 minutes; use these to wait less or return right away. If the render isn't done, read prints the render command to run next.

10. Get a Render

Get the result of a read that was still rendering. Takes the same --out, --max-wait-seconds, and --no-wait options as read.

shumai-cli render <taskId> --out frames

Development

To run the CLI in development mode inside the repository source code:

bun run apps/cli/src/index.ts project ls

Adding Commands

Most commands are generated from the shared Operation definitions in packages/operations (see "Operations" in AGENTS.md). An Operation with the cli surface and a cli spec becomes a command automatically, with arguments, options, and help text derived from its input schema. It is also available to Shumai's built-in agent and MCP server. Behavior that needs the local machine, such as downloading files, goes in a CLI extension in src/operations/extensions/ (extra options, input mapping, and output). Only commands that stream local files (upload, create-version) are written by hand in src/program.ts.