Orchata CLI Commands
Orchata CLI 命令
Use this skill when you need to run
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 skill instead)
- You need tree-based document navigation (MCP only feature)
- You need programmatic function calls (use skill instead)
当你需要在终端/Shell环境中运行
命令时，请使用此技能。
适用场景：
- 需要在终端中运行Shell命令
- 需要执行批量文件上传
- 进行文件系统操作
- 需要编写脚本或自动化Orchata操作
- 需要JSON格式的输出用于解析
不适用场景：
- 可使用MCP工具时（请改用技能）
- 需要基于树状结构的文档导航（仅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
安装与设置
Install globally via npm
通过npm全局安装
npm install -g @orchata/cli
npm install -g @orchata/cli
yarn global add @orchata/cli
yarn global add @orchata/cli
Initial Configuration
初始配置
1. Configure CLI (run once after install)
1. 配置CLI（安装后运行一次）
2. Authenticate with your API key
2. 使用API密钥进行身份验证
3. Verify connection
3. 验证连接
Environment Variables
环境变量
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命令参考
bash
orchata spaces create --name "Product Docs" --description "Technical documentation" --icon book
Options:
- - Space name (required)
- - Space description (optional)
- - Icon: , , , , , , , , ,
bash
orchata spaces create --name "产品文档" --description "技术文档" --icon book
选项：
- - 空间名称（必填）
- - 空间描述（可选）
- - 图标选项：, , , , , , , , ,
Get a specific space
获取指定空间信息
bash
orchata spaces get space_abc123
bash
orchata spaces get space_abc123
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
List documents in a space
列出空间中的文档
bash
orchata documents list --space space_abc123
bash
orchata documents list --space space_abc123
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最强大的功能 - 一键上传整个目录的内容！
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 "额外内容..."
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 to query (required for basic query)
- - Maximum number of results (default: 10)
bash
orchata query "安装指南" --space space_abc123 --top-k 15
选项：
- - 要查询的空间ID（基础查询必填）
- - 最大结果数量（默认：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"
当你不知道该查询哪个空间时，此功能可帮助你找到相关的空间。
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:
- - Use a named profile
- - Override API base URL
- - Override app base URL
- - Override API key for this run
- - Output raw JSON (useful for scripting)
这些选项适用于所有命令：
bash
orchata spaces list --profile production
orchata query "测试" --space space_123 --api-key oai_custom_key --json
可用全局选项：
- - 使用指定名称的配置文件
- - 覆盖API基础URL
- - 覆盖应用基础URL
- - 本次运行使用自定义API密钥
- - 输出原始JSON（适用于脚本编写）
Pattern 1: Upload files and query them
模式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
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
orchata query "认证流程" --space space_abc123
Pattern 2: Batch upload directory
模式2：批量上传目录
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：发现与搜索
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
orchata query "支付方式" --space space_billing
Pattern 4: Get raw JSON for scripting
模式4：获取原始JSON用于脚本
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：多环境配置文件管理
Login to different environments
登录到不同环境
orchata login --profile development
orchata login --profile production
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
Documents are processed asynchronously:
- Upload returns immediately with
- Background job generates embeddings and indexes the document (typically 1-3 seconds)
- Status changes to when ready
- Document becomes searchable
To check completion status:
文档为异步处理：
- 上传后立即返回
- 后台任务生成嵌入向量并索引文档（通常需要1-3秒）
- 处理完成后状态变为
- 文档可被搜索
检查处理完成状态：
List all documents with their status
列出所有文档及其状态
orchata documents list --space space_abc123
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等）
---
- Use batch upload for directories - is efficient
- Use 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
- 使用批量上传功能处理目录 - 效率更高
- 编写脚本时使用标志 - 便于程序化解析
- 上传后等待1-3秒 - 给文档留出处理时间
- 使用描述性的空间名称和描述 - 有助于空间发现
- 查询前检查文档状态 - 仅状态为COMPLETED的文档可被搜索
- 使用配置文件管理多环境 - 开发、 staging、生产环境
- 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 first
- Don't mix profile credentials - Use flag consistently
- 上传后立即查询 - 等待处理完成后再查询
- 使用过短的查询语句 - 上下文越详细，结果越准确
- 忘记身份验证 - 先运行
- 混合配置文件凭据 - 始终使用标志区分
"Command not found: orchata"
"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"
"Authentication required"
Or set environment variable:
或设置环境变量：
export ORCHATA_API_KEY="oai_..."
export ORCHATA_API_KEY="oai_..."
"Space not found"
"Space not found"
Use the exact space ID from the list
使用列表中的准确空间ID
"Document still processing"
"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字段
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)
常见原因：
- 文件过大（检查文件大小限制）
- 文件格式无效（检查上述支持的格式）
- 空间已归档（使用其他空间）
- 网络问题（检查连接）
The CLI stores configuration in
:
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
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
| Task | Command |
|---|
| List spaces | |
| 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 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
|
| 发现空间 | |
| JSON输出 | orchata spaces list --json
|
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"
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
orchata query "summary of document" --space "${SPACE_ID}"
orchata query "文档摘要" --space "${SPACE_ID}"
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)
space = run_orchata('spaces create --name "My Docs"')
space_id = space['space']['id']
space = run_orchata('spaces create --name "我的文档"')
space_id = space['space']['id']
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)
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 (, )
- ❌ Direct document updates (use upload with same filename to replace)
- ❌ Compact query format (always returns full results)
CLI excels at:
- ✅ Batch file operations ()
- ✅ Scripting and automation
- ✅ JSON output for parsing
- ✅ Profile management for multiple environments
- ✅ File system integration
For tree-based navigation and programmatic access, use the skill instead. CLI不支持：
- ❌ 基于树状结构的文档导航（, ）
- ❌ 直接更新文档（使用相同文件名上传来替换）
- ❌ 紧凑查询格式（始终返回完整结果）
CLI擅长：
- ✅ 批量文件操作（）
- ✅ 脚本编写与自动化
- ✅ 可解析的JSON输出
- ✅ 多环境配置文件管理
- ✅ 文件系统集成