Team Handbook · CLI / Skill

Put team context in one workspace,
let cloud agents execute

Connect once, then use your local terminal to find team materials, upload files, delegate work, and manage schedules. Cloud task artifacts return to the same workspace for permitted reuse.

For Kimi Code / Claude Code and other local agents One-time CLI setup Document version: 2026-11-12
01

Overview in one minute

Separate shared context, personal access, and cloud execution into three clear layers.

Workspace = shared memory

Files, artifacts, and share links stay in workspaces and work items. Members and later tasks can reuse authorized materials.

CLI = personal access

Each person uses an API key bound to one workspace, with configuration stored locally. Work from your own terminal without switching pages.

Cloud agent = execution layer

Tasks run in the cloud with workspace materials, connected resources, and available skills. Reviewable results return as artifacts.

What this means for a team

ModeHow it worksWhat it improves
Knowledge retentionUpload files and keep reports as artifacts for later referenceReduce scattered files and handover costs
DelegationOne local instruction creates a cloud task with real inputs and artifactsReduce waiting and repeated coordination
Recurring workTurn stable routines into schedules with a fixed result scopeMake execution repeatable instead of memory-dependent
Parallel workstreamsOrganize materials and tasks by work itemKeep project scopes clear
02

Setup in three steps

Create the key on the web, then let your local agent install and verify the connection.

1

Step 1: Create an API keyWeb · You

  1. Open the target workspace and click the settings (gear) icon in the top-right corner.
  2. In the AI Agent Settings window, find the API Keys section.
  3. Enter a name such as zhang-agent, optionally set an expiry time, and click Create.
  4. The full key is shown once. Copy it immediately and store it safely.
Three constraints: a key is bound to one workspace; operations follow your current permissions; each person can have up to 5 active keys per workspace. Member-based names and expiry dates support security and auditing.
2

Install through your local agentLocal terminal · Agent

Open the CLI quickstart, copy its complete installation prompt into Kimi Code or Claude Code, and provide the key when asked. Your agent needs network access.

Open the CLI quickstart and copy the installation prompt →
Manual setup is also available: curl -fsSL https://www.craepas.ai/cli/setup.sh | bash. The interactive script asks for your API key.
3

Verify the connectionLocal terminal · Agent

The agent runs setup.sh --profile default, stores the configuration in ~/.craepas/profiles/default.json, then reads GET /api/cli/apidoc. Environment variables containing the key are scoped to the setup command.

What success looks like: the agent reports the selected profile, bound workspace, visible work items, and deployed API version. Treat the live response as authoritative rather than expecting fixed counts or versions.
Connecting another workspace: use a new profile name. Never overwrite a profile that belongs to a different connection, and explicitly select the profile during verification.
03

What you can do

Ten capabilities covering context, files, delegation, schedules, and results.

Workspace query

Confirm the connected workspace

GET /workspace
Work item query

Find the target workItemId

GET /workitems
Context search

Search indexed files and artifacts

GET /search
Artifact access

Read agent-produced deliverables

GET /artifacts
Upload access

Read files uploaded by users

GET /uploads
File upload

Upload local files to the selected scope

POST /uploads
Share resolution

Resolve authorized Drive share links

POST /share/resolve
Immediate delegation

Submit and track cloud agent tasks

POST /tasks
Schedule management

Create, query, and edit schedules

POST·PATCH /scheduled-tasks
Run history

Review scheduled execution records

GET /scheduled-tasks/{id}/runs
Use apidoc as the contract: these short paths are memory aids. Ask your agent to read GET /api/cli/apidoc before each task for actual endpoints, parameters, responses, and pagination rules.
04

Five typical workflows

After setup, give these instructions to your external agent. Start with GET /api/cli/apidoc and replace example work items, files, and times with real values.

Scenario 1: Find workspace or work item context

GET /search · GET /uploads · GET /artifacts
Scenario 1

The key is bound to one workspace. Read the workspace and existing work items before selecting workItemId. Search without workItemId includes child work items; specifying it narrows the scope.

① Confirm scopeRead apidoc and the workspace
›
② Select a work itemFind its workItemId
›
③ SearchReview sources and summaries
›
④ Read originalsDownload when verification matters
Prompt · Scenario 1
Read the live apidoc, confirm the workspace and list existing work items. Find the workItemId for “Monthly business analysis”, search that work item for “sales daily report”, and list sources and summaries. Download originals when needed for verification.
Search scope: omitting workItemId includes child work items. Search covers indexed metadata and summaries, not full file bodies, and indexing may lag. Use exact identifiers for critical tasks.

Scenario 2: Upload a batch with a manifest

POST /uploads · complete
Scenario 2

Upload files and their manifest to the same scope. Save returned objectKey values rather than inventing paths, and record batchId, objectKey / originalName, and processing instructions.

① Upload filesRecord each successful objectKey
›
② Confirm completionDirect uploads require complete
›
③ Write a manifestInclude files and requirements
›
④ Upload togetherKeep the same scope
Prompt · Scenario 2
Upload files from local ./reports/ to the confirmed work item and record each successful objectKey. After all succeed, create and upload batch-manifest.json with the file list and instructions to produce a Chinese daily report. Return the manifest identifier and upload results; list any failures.
Common pitfall: save returned objectKey values instead of constructing paths. Matching filenames do not imply replacement or identify a batch; use batchId for batch identity.

Scenario 3: Delegate work remotely and retrieve results

POST /api/cli/tasks
Scenario 3

For immediate work, create a task without a conversation or schedule. Include actual resource identifiers and requirements, save the runId, query until terminal, and read result artifacts through Drive.

① Prepare inputsFind files, skills, and connectors
›
② Create a taskSet title, instruction, and scope
›
③ Keep runIdPoll until a terminal state
›
④ Collect resultsRead result and download artifacts
Prompt · Scenario 3
Confirm the workspace and work item, find existing sales materials and available skills and connectors, and delegate sales analysis to the cloud agent immediately with a Chinese report as the deliverable. Reuse workspace materials and ask me if essential information is missing. Return the runId, track the task until it ends, read the result and download the artifacts locally.
Two essentials: omitting workItemId selects workspace scope; including it selects a work item. Put real objectKey / artifactId values and delivery requirements in the instruction. Delegation requires Agent permission and AI quota.

Scenario 4: Create and maintain schedules

POST·PATCH /api/cli/scheduled-tasks
Scenario 4

Create an active schedule for future or recurring work. Specify timezone for recurring wall-clock times, and include the desired workItemId in full-form edits.

① Choose a ruleonce / interval / daily / weekly
›
② Set timezoneRequired for recurring wall-clock rules
›
③ CreateNew definitions become active
›
④ MaintainUse a full form or status-only PATCH
Prompt · Scenario 4
Read apidoc and confirm the uploaded manifest. Create a one-time schedule in that same work item using my specified future time and timezone. Ask me for a concrete time if missing. Read details before later edits; pause with {"status":"paused"} and resume with {"status":"active"}.
Scope trap: full-form edits must include the desired workItemId; omitting it or sending null selects workspace root. Status-only pause or enable updates retain scope.

Scenario 5: Query run history and download artifacts

GET /scheduled-tasks/{id}/runs[/{runId}]
Scenario 5

Review shared run history, then list Drive artifacts in the same scope and download by artifactId. Uploads and artifacts have separate lists.

① List historyUse limit / offset pagination
›
② Check statusReturn later if still running
›
③ Find artifactsStay in the same scope
›
④ DownloadUse the confirmed artifactId
Prompt · Scenario 5
Read recent runs for that schedule and list statuses and result summaries. If still running, check later. Once complete, find artifacts linked to that run in the same work item and download the daily report. If the association cannot be confirmed, explain instead of selecting an unrelated report.
Permission detail: shared history can include other members’ statuses and result summaries. Single-run detail is limited to the key user; another user’s detail returns 404. Omitting workItemId lists only workspace-root Drive content.
05

Team collaboration rules

Five habits keep a shared workspace useful instead of disorganized.

RulePracticeWhy
Keys represent peopleName keys by member, set expiry dates, and rotate them. Do not persist keys in shell configuration.Operations follow the creator’s permissions and leave a useful audit trail.
Scope disciplineState whether uploads, tasks, and schedules belong to a work item or workspace root.Omitting workItemId selects workspace root, which can scatter outputs.
Input conventionsUse manifests for batches and pass real objectKey values instead of vague file descriptions.Guessed paths and matching filenames do not establish identity.
Recurring inputsTell the schedule how to select each period’s inputs, such as files uploaded in the last seven days.A fixed manifest can repeatedly process the same old batch.
Quota awarenessEstimate AI usage before batch delegation; use search when delegation is unnecessary.AI quota is a shared team resource.
Start with a pilot: choose one real workflow, set up its work item structure and first schedule, and let the team use it for a week before broader rollout.
06

Limits and common misunderstandings

Knowing what the CLI does not expose avoids unnecessary troubleshooting.

Workspace and work item records are read-onlyThe CLI can query them, upload files, and create tasks, but cannot edit their structure or properties.
No schedule run-nowUse an immediate task for work that should run now; schedules handle future or recurring execution.
No schedule deletion or notification resendThe CLI can create, query, edit, pause, and enable schedules. Pause definitions you no longer need.
Indexing may lagSearch covers indexed metadata and summaries. Use exact identifiers for critical tasks instead of relying on immediate search visibility.
Other users’ run details are privateShared history remains visible, but single-run detail is user-isolated and returns 404 for another user’s run.
Uploads and artifacts are separate listsQuery them separately. Omitting workItemId lists only workspace-root content, not child work items.
07

Quick reference

A minimal set for a team wiki or workstation.

Core commands and identifiers

Skill name
craepas-cli
Skill files
https://www.craepas.ai/cli/SKILL.md
https://www.craepas.ai/cli/setup.sh
Profile
~/.craepas/profiles/default.json
API base URL
https://api.craepas.ai
Authentication
Authorization: Bearer ak_xxxxxxxx_...
Immediate / scheduled
POST /api/cli/tasks · POST /api/cli/scheduled-tasks
Schedule rules
once · interval · daily · weekly
Pause / resume
PATCH {"status":"paused"} · {"status":"active"}
Manual setup and live API discovery
curl -fsSL https://www.craepas.ai/cli/setup.sh | bash

curl -fsS -H "Authorization: Bearer ${CLI_API_KEY}" \
  "${CLI_API_BASE_URL:-https://api.craepas.ai}/api/cli/apidoc"