From 4e21becbe03cc322e487ec698db5dc0d56e59493 Mon Sep 17 00:00:00 2001 From: yiling Date: Sun, 21 Jun 2026 21:54:45 +0800 Subject: [PATCH] docs(cli): add CLI documentation and link to it in root README --- README.md | 8 ++++ apps/cli/README.md | 97 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 105 insertions(+) create mode 100644 apps/cli/README.md diff --git a/README.md b/README.md index 515f1b2b..04fc8c0d 100644 --- a/README.md +++ b/README.md @@ -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). diff --git a/apps/cli/README.md b/apps/cli/README.md new file mode 100644 index 00000000..fddc7f05 --- /dev/null +++ b/apps/cli/README.md @@ -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 [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 +``` + +- **Options:** + - `-p`, `--parent `: The parent folder ID (required). + +#### 3. Create a New Folder + +Create a new folder under a parent folder. + +```bash +shumai-cli mkdir -p +``` + +- **Options:** + - `-p`, `--parent `: 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 -p +``` + +- **Options:** + - `-p`, `--parent `: 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 -p +``` + +- **Options:** + - `-p`, `--parent `: 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 +```