orchata-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Orchata CLI Commands

Orchata CLI 命令

Use this skill when you need to run

orchata

commands in a terminal/shell environment.

Use when:

You need to run shell commands in a terminal
You need to perform batch file uploads
You're working with file system operations
You need to script or automate Orchata operations
You want JSON output for parsing

Don't use when:

You have MCP tools available (use
```
orchata-mcp
```
skill instead)
You need tree-based document navigation (MCP only feature)
You need programmatic function calls (use
```
orchata-mcp
```
skill instead)

当你需要在终端/Shell环境中运行

orchata

命令时，请使用此技能。

适用场景：

需要在终端中运行Shell命令
需要执行批量文件上传
进行文件系统操作
需要编写脚本或自动化Orchata操作
需要JSON格式的输出用于解析

不适用场景：

可使用MCP工具时（请改用
```
orchata-mcp
```
技能）
需要基于树状结构的文档导航（仅MCP支持的功能）
需要程序化函数调用时（请改用
```
orchata-mcp
```
技能）

What is Orchata?

什么是Orchata？

Orchata is a knowledge management platform that:

Organizes documents into Spaces - Logical containers for related content
Provides semantic search - Find relevant content using natural language queries
Provides CLI - Terminal interface for document management and queries

Orchata是一款知识管理平台，具备以下特性：

将文档组织到空间中 - 相关内容的逻辑容器
提供语义搜索 - 使用自然语言查询查找相关内容
提供CLI工具 - 用于文档管理和查询的终端界面

Installation & Setup

安装与设置

Installation

安装

bash

undefined

bash

undefined

Install globally via npm

通过npm全局安装

npm install -g @orchata/cli

Or via bun

或通过bun安装

bun add -g @orchata/cli

Or via pnpm

或通过pnpm安装

pnpm add -g @orchata/cli

Or via yarn

或通过yarn安装

yarn global add @orchata/cli

Verify installation

验证安装

orchata --version

undefined

orchata --version

undefined

Initial Configuration

初始配置

bash

undefined

bash

undefined

1. Configure CLI (run once after install)

1. 配置CLI（安装后运行一次）

orchata init

2. Authenticate with your API key

2. 使用API密钥进行身份验证

orchata login

3. Verify connection

3. 验证连接

orchata spaces list

undefined

orchata spaces list

undefined

Environment Variables

环境变量

bash

undefined

bash

undefined

Optional: Override settings via environment variables

可选：通过环境变量覆盖设置

export ORCHATA_API_KEY="oai_..." export ORCHATA_API_BASE="https://api.orchata.ai" export ORCHATA_PROFILE="production"

---

export ORCHATA_API_KEY="oai_..." export ORCHATA_API_BASE="https://api.orchata.ai" export ORCHATA_PROFILE="production"

---

CLI Commands Reference

CLI命令参考

Space Management

空间管理

List all spaces

列出所有空间

bash

orchata spaces list

bash

orchata spaces list

Create a space

创建空间

bash

orchata spaces create --name "Product Docs" --description "Technical documentation" --icon book

Options:

```
--name <name>
```
- Space name (required)
```
--description <text>
```
- Space description (optional)

--icon <icon>

- Icon:

folder

book

file-text

database

package

archive

briefcase

inbox

layers

box

bash

orchata spaces create --name "产品文档" --description "技术文档" --icon book

选项：

```
--name <name>
```
- 空间名称（必填）
```
--description <text>
```
- 空间描述（可选）

--icon <icon>

- 图标选项：

folder

book

file-text

database

package

archive

briefcase

inbox

layers

box

Get a specific space

获取指定空间信息

bash

orchata spaces get space_abc123

bash

orchata spaces get space_abc123

Update a space

更新空间

bash

orchata spaces update space_abc123 --name "Updated Name" --description "New description"

bash

orchata spaces update space_abc123 --name "更新后的名称" --description "新描述"

Delete a space (soft delete/archive)

删除空间（软删除/归档）

bash

orchata spaces delete space_abc123

bash

orchata spaces delete space_abc123

Document Management

文档管理

List documents in a space

列出空间中的文档

bash

orchata documents list --space space_abc123

bash

orchata documents list --space space_abc123

Upload a file

上传文件

bash

orchata documents upload ./path/to/file.pdf --space space_abc123
orchata documents upload ./guide.md --space space_abc123

bash

orchata documents upload ./path/to/file.pdf --space space_abc123
orchata documents upload ./guide.md --space space_abc123

Upload inline content

上传内嵌内容

bash

orchata documents upload --space space_abc123 --content "# Title\n\nContent here..."

bash

orchata documents upload --space space_abc123 --content "# 标题\n\n内容..."

Batch upload (directory)

批量上传（目录）

bash

orchata documents batch ./docs/ --space space_abc123

This is the most powerful CLI feature - upload entire directories in one command!

bash

orchata documents batch ./docs/ --space space_abc123

这是CLI最强大的功能 - 一键上传整个目录的内容！

Get a document

获取文档信息

bash

orchata documents get doc_xyz789 --space space_abc123

bash

orchata documents get doc_xyz789 --space space_abc123

Get document content (processed text)

获取文档内容（处理后的文本）

bash

orchata documents content doc_xyz789 --space space_abc123

bash

orchata documents content doc_xyz789 --space space_abc123

Append to a document

追加内容到文档

bash

orchata documents append doc_xyz789 --space space_abc123 --content "Additional content..."

bash

orchata documents append doc_xyz789 --space space_abc123 --content "额外内容..."

Querying

查询功能

Query a specific space

查询指定空间

bash

orchata query "How do I authenticate?" --space space_abc123

bash

orchata query "如何进行身份验证？" --space space_abc123

Query with more results

查询更多结果

bash

orchata query "installation guide" --space space_abc123 --top-k 15

Options:

```
--space <id>
```
- Space ID to query (required for basic query)
```
--top-k <n>
```
- Maximum number of results (default: 10)

bash

orchata query "安装指南" --space space_abc123 --top-k 15

选项：

```
--space <id>
```
- 要查询的空间ID（基础查询必填）
```
--top-k <n>
```
- 最大结果数量（默认：10）

Smart query (discover relevant spaces)

智能查询（发现相关空间）

bash

orchata query smart "what is orchata"

This helps you find which spaces are relevant when you don't know where to look.

bash

orchata query smart "什么是Orchata"

当你不知道该查询哪个空间时，此功能可帮助你找到相关的空间。

Global Options

全局选项

These options work with any command:

bash

orchata spaces list --profile production
orchata query "test" --space space_123 --api-key oai_custom_key --json

Available global options:

```
--profile <name>
```
- Use a named profile
```
--api-base <url>
```
- Override API base URL
```
--app-base <url>
```
- Override app base URL
```
--api-key <key>
```
- Override API key for this run
```
--json
```
- Output raw JSON (useful for scripting)

这些选项适用于所有命令：

bash

orchata spaces list --profile production
orchata query "测试" --space space_123 --api-key oai_custom_key --json

可用全局选项：

```
--profile <name>
```
- 使用指定名称的配置文件
```
--api-base <url>
```
- 覆盖API基础URL
```
--app-base <url>
```
- 覆盖应用基础URL
```
--api-key <key>
```
- 本次运行使用自定义API密钥
```
--json
```
- 输出原始JSON（适用于脚本编写）

Common Patterns

常见使用模式

Pattern 1: Upload files and query them

模式1：上传文件并查询

bash

undefined

bash

undefined

1. Create a space

1. 创建空间

orchata spaces create --name "Docs" --description "Product documentation"

orchata spaces create --name "文档" --description "产品文档"

Returns: space_abc123

返回：space_abc123

2. Upload documents

2. 上传文档

orchata documents upload ./handbook.pdf --space space_abc123 orchata documents upload ./api-guide.md --space space_abc123

3. Wait ~1-3 seconds for processing, then query

3. 等待约1-3秒处理完成，然后查询

orchata query "authentication flow" --space space_abc123

undefined

orchata query "认证流程" --space space_abc123

undefined

Pattern 2: Batch upload directory

模式2：批量上传目录

bash

undefined

bash

undefined

Upload all files in a directory

上传目录中的所有文件

orchata documents batch ./documentation/ --space space_abc123


**This is ideal for:**
- Initial knowledge base setup
- Bulk document imports
- Directory synchronization

orchata documents batch ./documentation/ --space space_abc123


**此功能非常适合：**
- 知识库初始搭建
- 批量文档导入
- 目录同步

Pattern 3: Discover and search

模式3：发现与搜索

bash

undefined

bash

undefined

1. Find relevant spaces

1. 查找相关空间

orchata query smart "billing questions"

orchata query smart "计费问题"

Returns: space_billing (most relevant)

返回：space_billing（最相关）

2. Query that space

2. 查询该空间

orchata query "payment methods" --space space_billing

undefined

orchata query "支付方式" --space space_billing

undefined

Pattern 4: Get raw JSON for scripting

模式4：获取原始JSON用于脚本

bash

undefined

bash

undefined

Get JSON output for parsing

获取可解析的JSON输出

orchata spaces list --json | jq '.spaces[] | .id' orchata query "test" --space space_123 --json | jq '.results[0].content'


**Use JSON mode for:**
- Shell scripts
- CI/CD pipelines
- Automation workflows
- Data processing

orchata spaces list --json | jq '.spaces[] | .id' orchata query "测试" --space space_123 --json | jq '.results[0].content'


**JSON模式适用于：**
- Shell脚本
- CI/CD流水线
- 自动化工作流
- 数据处理

Pattern 5: Profile management for multiple environments

模式5：多环境配置文件管理

bash

undefined

bash

undefined

Login to different environments

登录到不同环境

orchata login --profile development orchata login --profile production

Use specific profile

使用指定配置文件

orchata query "test" --space space_123 --profile production

---

orchata query "测试" --space space_123 --profile production

---

Document Processing

文档处理

Documents are processed asynchronously:

Upload returns immediately with
```
status="PROCESSING"
```
Background job generates embeddings and indexes the document (typically 1-3 seconds)
Status changes to
```
"COMPLETED"
```
when ready
Document becomes searchable

To check completion status:

bash

undefined

文档为异步处理：

上传后立即返回
```
status="PROCESSING"
```
后台任务生成嵌入向量并索引文档（通常需要1-3秒）
处理完成后状态变为
```
"COMPLETED"
```
文档可被搜索

检查处理完成状态：

bash

undefined

List all documents with their status

列出所有文档及其状态

orchata documents list --space space_abc123

Check specific document

检查指定文档

orchata documents get doc_xyz789 --space space_abc123


**Supported file formats:**
- PDF (text-based and scanned with OCR)
- Word documents (.docx)
- Excel spreadsheets (.xlsx)
- PowerPoint presentations (.pptx)
- Markdown files (.md)
- Plain text files (.txt)
- Images (PNG, JPG, etc.)

---

orchata documents get doc_xyz789 --space space_abc123


**支持的文件格式：**
- PDF（基于文本和带OCR的扫描件）
- Word文档（.docx）
- Excel表格（.xlsx）
- PowerPoint演示文稿（.pptx）
- Markdown文件（.md）
- 纯文本文件（.txt）
- 图片（PNG、JPG等）

---

Best Practices

最佳实践

DO

建议

Use batch upload for directories -
```
orchata documents batch
```
is efficient
Use
--json
flag for scripting - Easy to parse programmatically
Wait 1-3 seconds after upload - Give documents time to process
Use descriptive space names and descriptions - Helps with discovery
Check document status before querying - Only COMPLETED documents are searchable
Use profiles for multiple environments - dev, staging, production

使用批量上传功能处理目录 -
```
orchata documents batch
```
效率更高
编写脚本时使用
--json
标志 - 便于程序化解析
上传后等待1-3秒 - 给文档留出处理时间
使用描述性的空间名称和描述 - 有助于空间发现
查询前检查文档状态 - 仅状态为COMPLETED的文档可被搜索
使用配置文件管理多环境 - 开发、 staging、生产环境

DON'T

不建议

Don't query immediately after upload - Wait for processing to complete
Don't use very short queries - More context = better results
Don't forget to authenticate - Run
```
orchata login
```
first
Don't mix profile credentials - Use
```
--profile
```
flag consistently

上传后立即查询 - 等待处理完成后再查询
使用过短的查询语句 - 上下文越详细，结果越准确
忘记身份验证 - 先运行
```
orchata login
```
混合配置文件凭据 - 始终使用
```
--profile
```
标志区分

Troubleshooting

故障排除

"Command not found: orchata"

Solution:

bash

npm install -g @orchata/cli
orchata --version

Verify the CLI is installed and in your PATH.

解决方案：

bash

npm install -g @orchata/cli
orchata --version

验证CLI已安装且在PATH中。

"Authentication required"

Solution:

bash

orchata login

解决方案：

bash

orchata login

Or set environment variable:

或设置环境变量：

export ORCHATA_API_KEY="oai_..."

undefined

export ORCHATA_API_KEY="oai_..."

undefined

"Space not found"

Solution:

bash

orchata spaces list

解决方案：

bash

orchata spaces list

Use the exact space ID from the list

使用列表中的准确空间ID

undefined

undefined

"Document still processing"

Solution: Wait 1-3 seconds after upload for processing to complete:

bash

orchata documents list --space <space_id>

解决方案： 上传后等待1-3秒，待处理完成：

bash

orchata documents list --space <space_id>

Check status field

查看status字段

undefined

undefined

Upload fails

上传失败

Common causes:

File is too large (check file size limits)
Invalid file format (check supported formats above)
Space is archived (use a different space)
Network issues (check connection)

常见原因：

文件过大（检查文件大小限制）
文件格式无效（检查上述支持的格式）
空间已归档（使用其他空间）
网络问题（检查连接）

Configuration Files

配置文件

The CLI stores configuration in

~/.orchata/config.json

json

{
  "profiles": {
    "default": {
      "apiKey": "oai_...",
      "apiBase": "https://api.orchata.ai",
      "appBase": "https://app.orchata.ai"
    },
    "production": {
      "apiKey": "oai_...",
      "apiBase": "https://api.orchata.ai"
    }
  },
  "defaultProfile": "default"
}

You can also manage configuration with:

bash

orchata configure --api-base https://api.orchata.ai
orchata configure --profile production --set-default

CLI将配置存储在

~/.orchata/config.json

中：

json

{
  "profiles": {
    "default": {
      "apiKey": "oai_...",
      "apiBase": "https://api.orchata.ai",
      "appBase": "https://app.orchata.ai"
    },
    "production": {
      "apiKey": "oai_...",
      "apiBase": "https://api.orchata.ai"
    }
  },
  "defaultProfile": "default"
}

你也可以通过以下命令管理配置：

bash

orchata configure --api-base https://api.orchata.ai
orchata configure --profile production --set-default

Quick Reference

速查表

Task	Command
List spaces	`orchata spaces list`
Create space	`orchata spaces create --name "Docs"`
Get space	`orchata spaces get space_123`
List documents	`orchata documents list --space space_123`
Upload file	`orchata documents upload ./file.pdf --space space_123`
Batch upload	`orchata documents batch ./dir/ --space space_123`
Get document	`orchata documents get doc_123 --space space_123`
Search content	`orchata query "question" --space space_123`
Discover spaces	`orchata query smart "question"`
JSON output	`orchata spaces list --json`

任务	命令
列出空间	`orchata spaces list`
创建空间	`orchata spaces create --name "文档"`
获取空间信息	`orchata spaces get space_123`
列出文档	`orchata documents list --space space_123`
上传文件	`orchata documents upload ./file.pdf --space space_123`
批量上传	`orchata documents batch ./dir/ --space space_123`
获取文档信息	`orchata documents get doc_123 --space space_123`
搜索内容	`orchata query "问题" --space space_123`
发现空间	`orchata query smart "问题"`
JSON输出	`orchata spaces list --json`

Script Examples

脚本示例

Bash: Upload and wait for processing

Bash：上传并等待处理完成

bash

#!/bin/bash

SPACE_ID="space_abc123"
FILE="./document.pdf"

bash

#!/bin/bash

SPACE_ID="space_abc123"
FILE="./document.pdf"

Upload

上传

echo "Uploading ${FILE}..." RESULT=$(orchata documents upload "${FILE}" --space "${SPACE_ID}" --json) DOC_ID=$(echo $RESULT | jq -r '.document.id')

echo "Document ID: ${DOC_ID}" echo "Waiting for processing..."

echo "正在上传${FILE}..." RESULT=$(orchata documents upload "${FILE}" --space "${SPACE_ID}" --json) DOC_ID=$(echo $RESULT | jq -r '.document.id')

echo "文档ID：${DOC_ID}" echo "等待处理完成..."

Wait for completion

等待处理完成

while true; do STATUS=$(orchata documents get "${DOC_ID}" --space "${SPACE_ID}" --json | jq -r '.document.status')

if [ "$STATUS" = "COMPLETED" ]; then echo "Processing complete!" break elif [ "$STATUS" = "FAILED" ]; then echo "Processing failed!" exit 1 fi

echo "Status: ${STATUS}..." sleep 2 done

while true; do STATUS=$(orchata documents get "${DOC_ID}" --space "${SPACE_ID}" --json | jq -r '.document.status')

if [ "$STATUS" = "COMPLETED" ]; then echo "处理完成！" break elif [ "$STATUS" = "FAILED" ]; then echo "处理失败！" exit 1 fi

echo "状态：${STATUS}..." sleep 2 done

Query

查询

orchata query "summary of document" --space "${SPACE_ID}"

undefined

orchata query "文档摘要" --space "${SPACE_ID}"

undefined

Python: Batch upload with status checking

Python：批量上传并检查状态

python

import subprocess
import json
import time

def run_orchata(command):
    """Run orchata CLI command and return JSON result"""
    cmd = f"orchata {command} --json"
    result = subprocess.run(cmd, shell=True, capture_output=True, text=True)
    return json.loads(result.stdout)

python

import subprocess
import json
import time

def run_orchata(command):
    """运行Orchata CLI命令并返回JSON结果"""
    cmd = f"orchata {command} --json"
    result = subprocess.run(cmd, shell=True, capture_output=True, text=True)
    return json.loads(result.stdout)

Create space

创建空间

space = run_orchata('spaces create --name "My Docs"') space_id = space['space']['id']

space = run_orchata('spaces create --name "我的文档"') space_id = space['space']['id']

Batch upload

批量上传

print(f"Uploading to space: {space_id}") run_orchata(f'documents batch ./docs/ --space {space_id}')

print(f"正在上传到空间：{space_id}") run_orchata(f'documents batch ./docs/ --space {space_id}')

Wait for all documents to process

等待所有文档处理完成

print("Waiting for processing...") while True: docs = run_orchata(f'documents list --space {space_id}') pending = [d for d in docs['documents'] if d['status'] != 'COMPLETED']

if not pending:
    print("All documents processed!")
    break

print(f"{len(pending)} documents still processing...")
time.sleep(3)

print("等待处理完成...") while True: docs = run_orchata(f'documents list --space {space_id}') pending = [d for d in docs['documents'] if d['status'] != 'COMPLETED']

if not pending:
    print("所有文档处理完成！")
    break

print(f"仍有{len(pending)}个文档在处理中...")
time.sleep(3)

Query

查询

results = run_orchata(f'query "main topics" --space {space_id}') print(json.dumps(results, indent=2))

---

results = run_orchata(f'query "主要主题" --space {space_id}') print(json.dumps(results, indent=2))

---

Differences from MCP Tools

与MCP工具的差异

CLI does NOT support:

❌ Tree-based document navigation (
```
get_document_tree
```
,
```
get_tree_node
```
)
❌ Direct document updates (use upload with same filename to replace)
❌ Compact query format (always returns full results)

CLI excels at:

✅ Batch file operations (
```
orchata documents batch
```
)
✅ Scripting and automation
✅ JSON output for parsing
✅ Profile management for multiple environments
✅ File system integration

For tree-based navigation and programmatic access, use the
orchata-mcp
skill instead.

CLI不支持：

❌ 基于树状结构的文档导航（
```
get_document_tree
```
,
```
get_tree_node
```
）
❌ 直接更新文档（使用相同文件名上传来替换）
❌ 紧凑查询格式（始终返回完整结果）

CLI擅长：

✅ 批量文件操作（
```
orchata documents batch
```
）
✅ 脚本编写与自动化
✅ 可解析的JSON输出
✅ 多环境配置文件管理
✅ 文件系统集成

如需树状导航和程序化访问，请改用
orchata-mcp
技能。