Files
shumai/apps/cli/README.md
T
Yiling-J 4ac274cdd4 feat(runner): replace server-side bash sandbox with remote runner (#530)
* feat(runner): replace server-side bash sandbox with remote runner

* fix(runner): address review findings for output bounds, key rotation, defaults, and generated uploads

* chore(docker): remove sandbox privileges and env vars from remaining compose files

* feat(cli): add runner start with bundled SRT sandboxing (#535)

* refactor(agent): expose runner bash without skill gating

* feat(cli): add runner start with optional SRT sandboxing

* refactor(cli): remove runner Python dependency

* feat(cli): bundle SRT and use platform-native runner shells

* refactor(cli): delegate runner processes to Execa

* chore(cli): upgrade @anthropic-ai/sandbox-runtime to 0.0.83

* feat(cli): discover Bash for Windows runners

Use Pi-style Bash discovery and launch behavior, exercise the packaged CLI shell, and wait for pending ZIP metadata reads before closing cancelled downloads.

* fix(runner): enforce ownership and safe reconnects

Gate dispatch on reconciliation, retain cancellations across disconnects, and stop replaced clients. Guard the single-server runner topology with a database lease. Restage missing generated inputs, report signal exits, and bound generated-file cleanup.

* feat(webui): add Korean translations for agent runners

* feat(cli): add runner event logging and --verbose flag (#536)

* feat(cli): add runner event logging and --verbose flag

* fix(cli): log runner capacity rejections accurately and use monotonic duration
2026-11-18 15:58:57 +08:00

16 KiB

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

Standalone executable

Install the CLI without Node.js or Bun. The installers download a platform-specific executable from GitHub Releases and verify its SHA-256 checksum.

macOS / Linux:

curl -fsSL https://github.com/shumaiOne/shumai/releases/latest/download/install.sh | sh

Windows (PowerShell):

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://github.com/shumaiOne/shumai/releases/latest/download/install.ps1 | iex"
Platform Architectures Requirements
macOS Apple Silicon, Intel macOS 13 or later
Linux ARM64, x64 glibc 2.17 or later; kernel 5.6+ recommended
Windows ARM64, x64 Windows 10 version 1809 or later

Native builds use Bun 1.4.4's runtime; x64 CPUs need SSE4.2. See Bun's system requirements. Alpine/musl is not included in these native downloads. Native downloads are available for releases containing the installer assets; use npm for earlier releases.

On macOS/Linux the default directory is ~/.local/bin. If it is missing from your current PATH, the installer prints a command to run in your current Bash/Zsh terminal:

export PATH="$HOME/.local/bin:$PATH"

To keep the CLI available in future terminals, add the same export line to ~/.bashrc (Bash) or ~/.zshrc (Zsh). For Bash login shells, use your existing login profile, such as ~/.bash_profile or ~/.profile. Open a new terminal after saving. If you already added it, you do not need to add it again. For a custom installation directory, use the exact command printed by the installer.

On Windows the installer uses %LOCALAPPDATA%\Shumai\bin and updates the user PATH. Open a new terminal afterward. Administrator access is not required.

Re-run the installer to upgrade. To pin a version, roll back, or choose an installation directory, download the installer and pass its options (replace X.Y.Z with a release containing native binaries):

curl -fsSL https://github.com/shumaiOne/shumai/releases/latest/download/install.sh -o install.sh
sh install.sh --version X.Y.Z --install-dir "$HOME/.local/bin"
Invoke-WebRequest https://github.com/shumaiOne/shumai/releases/latest/download/install.ps1 -OutFile install.ps1
& .\install.ps1 -Version X.Y.Z -InstallDir "$env:LOCALAPPDATA\Shumai\bin"

The installers preserve the existing executable if download or verification fails and refuse to replace unmanaged installations. If an npm installation takes precedence on PATH, uninstall it with npm uninstall -g @shumai-one/shumai-cli or adjust PATH.

To uninstall a native installation, remove shumai-cli (shumai-cli.exe on Windows) and .shumai-cli-install from its installation directory. Remove the PATH entry if it is no longer needed.

npm

The existing npm package continues to run on Node.js 22.12 or later:

npm install -g @shumai-one/shumai-cli

shumai-cli --version reports the installed version for either installation method.

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"

Agent runner

Create a runner in Settings → Agent Runners and copy its one-time key. On macOS, Linux, or Windows, start it in an existing dedicated workspace:

export SHUMAI_API_SERVER="https://shumai.example.com"
export SHUMAI_RUNNER_KEY="your-runner-key"
shumai-cli runner start --cwd /path/to/workspace

For Windows PowerShell:

$env:SHUMAI_API_SERVER = "https://shumai.example.com"
$env:SHUMAI_RUNNER_KEY = "your-runner-key"
shumai-cli runner start --cwd C:\workspace

Use --url or --key to override those variables. Pass -v or --verbose to log executed commands, output sizes, and file transfer paths (by default, only lifecycle events, execution IDs, exit status, and durations are printed to stderr). A runner key is separate from SHUMAI_API_KEY. The runner stays in the foreground; Ctrl+C stops it and its active commands. Remote servers require HTTPS; localhost and host.docker.internal support HTTP for development. No inbound port is opened.

Commands use /bin/sh on macOS and Linux. On Windows, the runner checks for Git Bash in the standard installation directories, then for bash.exe on PATH, then falls back to cmd.exe. It prints the selected shell at startup and reports it to the agent. Commands run with the local user's permissions unless SRT is requested.

Anthropic Sandbox Runtime is bundled with the CLI. Install its platform prerequisites (Linux: bubblewrap, socat, and ripgrep; macOS: ripgrep), then pass its native JSON settings:

shumai-cli runner start --srt sandbox.json

Windows sandboxing uses SRT's alpha Windows support. Use Git Bash if your selected shell is the legacy WSL Bash launcher. Run the one-time SRT setup before starting a sandboxed runner (it requests administrator permission):

npx @anthropic-ai/sandbox-runtime windows-install

SRT settings are read and validated at startup. Invalid settings or unavailable sandbox prerequisites stop startup; commands never fall back to unrestricted execution. Only shell commands and their children are sandboxed. Runner connections and server-directed file transfers stay outside SRT, and no server domain is automatically allowed. The shared SRT runtime is cleaned up when the runner stops.

See Agent Runners for configuration, Docker usage, limits, and security boundaries.

Usage

Important

For npm installations using Bun: The npm entry point uses #!/usr/bin/env node. Use bun run --bun shumai-cli project ls to run that package under Bun. Standalone installations already include their runtime.

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 and Create Projects

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

shumai-cli project ls

Create a new project (returns the project ID and its root folder ID):

shumai-cli project create "Project Name"

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

11. Download Files

Download up to 50 files at once. By default it saves the web preview version when there is one (for example the transcoded video or the web image), which is smaller; use --original for the uploaded file. A version stack downloads its latest version. Folders aren't supported: download the files inside them. Files keep their names; if a name is taken, the new file gets a number, like clip (2).mp4.

shumai-cli download <assetId...> --out ./downloads
shumai-cli download <assetId> --original
  • Options:
    • -o, --out <dir>: Folder to save the files in (default: the current folder). With --json, each file also gets a path.
    • --original: Download the original uploaded files instead of the web previews.

12. Search Files

Search a folder and all of its subfolders by name, or by meaning with --semantic (when AI search is enabled for the team).

shumai-cli search <query> -p <folderId>
shumai-cli search "a calm beach at sunset" -p <folderId> --semantic
  • Options:
    • -p, --parent <id>: The folder to search in (required).
    • --type <file|folder>: Search files (default) or folders.
    • --first <n>, --after <cursor>: Page through many results.

13. Copy Assets

Copy files or folders into another folder of the same team. Prints the IDs of the copies.

shumai-cli copy <assetId...> -p <parentId> [--with-comments]
# or using the short alias:
shumai-cli cp <assetId...> -p <parentId>

14. Comments

# List the comments on a file, with their replies
shumai-cli comment ls <assetId>
# Comment on a file, optionally at a timecode (seconds), or reply to a comment
shumai-cli comment add <assetId> "The logo is too small" --at 12.5
shumai-cli comment add <assetId> "Fixed in v2" --reply-to <commentId>
# Mark a comment as resolved, or unresolved again
shumai-cli comment resolve <commentId>
shumai-cli comment resolve <commentId> --reopen

15. Metadata

# List a project's metadata fields and their choices
shumai-cli field ls <projectId>
# Set metadata values on a file, as JSON keyed by field key (select fields take an option id)
shumai-cli meta set <assetId> --values '{"status": "approved", "rating": 4}'

16. Version Stacks

# Stack files in the same folder as versions; the first file is the latest
shumai-cli version stack <fileId...>
# List the versions in a stack, latest first
shumai-cli version ls <stackId>
# Take a version out of its stack (the file is kept)
shumai-cli version unstack <versionId>

17. Folder Instructions

Show a folder's instructions for AI agents (its AGENTS.md).

shumai-cli instructions <folderId>

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 (key/value inputs such as meta set --values take a JSON object). 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; the create_file, create_version, and complete_upload Operations are for the agent and MCP only.

Building and verifying native releases

bun run build:cli --target darwin-arm64 # or darwin-x64, linux-arm64, linux-x64, windows-arm64, windows-x64
bun run test:cli-release

Without --target, the build produces all six targets. Output defaults to out/cli-release. Set --out /absolute/path on either command to change it. Unix archives require tar. Creating Windows archives on Unix also requires zip. The test exercises installation, runner shell quoting, authenticated API calls, file transfers, and failure recovery. Install Git Bash to run the quoting check on Windows. With SRT configured, pass --srt /absolute/path/to/settings.json to repeat the quoting check in the sandbox.

The Native CLI workflow builds and tests each target on a matching runner. The npm release workflow assembles those tested archives, stages a draft GitHub Release, publishes npm packages, then publishes the completed release. Its validate_only dispatch input builds and tests without publishing. Published assets are verified and preserved on retries; draft assets can be replaced while resuming a failed run. Prerelease npm packages use the next tag and prerelease GitHub Releases do not become latest.

Installers use SHUMAI_CLI_RELEASE_BASE_URL only when explicitly set, for private mirrors or local testing. It should point to a release download base whose children are vX.Y.Z/<asset>. Native executables do not automatically load .env or bunfig.toml; export the API configuration explicitly as shown above.