docs(cli): add CLI documentation and link to it in root README

This commit is contained in:
yiling
2026-06-21 21:54:45 +08:00
parent 86c1d964a3
commit 4e21becbe0
2 changed files with 105 additions and 0 deletions
+8
View File
@@ -33,6 +33,14 @@
---
## Command Line Interface (CLI)
Shumai provides a Command Line Interface (CLI) tool to manage projects, folders, and assets, upload files/folders, and create new versions directly from your terminal.
For more details on installation and usage, see the [CLI Readme](apps/cli/README.md).
---
## Installation
Below is a quickstart guide for running Shumai with local storage. For advanced configuration options (including S3-compatible storage and Temporal workflow orchestration), see our [Documentation](https://docs.shumai.one/getting-started/overview).
+97
View File
@@ -0,0 +1,97 @@
# 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, and create new versions of existing files directly from the terminal.
---
## Installation
The CLI package is bundled inside the Shumai workspace.
### Environment Setup
Before using the CLI, you must set the following environment variables to authenticate with your Shumai instance:
```bash
# 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 -> Developer tab)
export SHUMAI_API_KEY="your-developer-api-token"
```
---
## Usage
Run `shumai-cli` or query specific commands:
```bash
shumai-cli <command> [arguments] [options]
```
### Commands
#### 1. List Projects
List all projects you have access to. Returns the project ID, name, and its root folder ID.
```bash
shumai-cli project ls
```
#### 2. List Directory Contents
List direct children (folders and files) of a parent folder.
```bash
shumai-cli ls -p <parentId>
```
- **Options:**
- `-p`, `--parent <id>`: The parent folder ID (required).
#### 3. Create a New Folder
Create a new folder under a parent folder.
```bash
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.
```bash
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.
```bash
shumai-cli create-version <localFilePath> -p <parentAssetId>
```
- **Options:**
- `-p`, `--parent <id>`: The parent asset ID (file or version stack) to version (required).
---
## Development
To run the CLI in development mode inside the repository source code:
```bash
bun run apps/cli/src/index.ts project ls
```