Connect a Workspace via CLI

External agents use a workspace API key to read workspace and work item data, access Drive uploads and artifacts, and search authorized context.

Read the CLI team collaboration handbook

Step 1: Create an API key

  1. Open the target workspace and click the settings (gear) icon in the top-right corner.

  2. In the AI Agent Settings window that opens, find the API Keys section below.

  3. Enter a name (e.g. xx-agent), optionally set an expiry time, and click "Create".

  4. After the key is created, the full API key is shown once — click "Copy" and store it safely.

The API key is bound to the current workspace and operations remain subject to current user permissions. Each user can create up to 5 active keys per workspace.

Step 2: Run the setup script

On the machine where you want to use the CLI, run the following command to download and run the interactive setup script:

curl -fsSL https://www.craepas.ai/cli/setup.sh | bash

Once configured, the settings are written to ~/.craepas/profiles/default.json (readable only by the current user). Afterwards, all requests just read the configuration from that file or environment variables, and call the APIs with the API key in the Authorization header:

Authorization: Bearer ak_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Configure it in your local agent

Copy the prompt below and send it to your local agent (such as Kimi Code, Claude Code, etc.). It will automatically download and install the skill, then complete configuration and connection verification. Create the API key in step 1 above.

Install an agent skill for me to connect to my Craepas workspace.

Skill name: craepas-cli
Skill files:
- https://www.craepas.ai/cli/SKILL.md
- https://www.craepas.ai/cli/setup.sh

Please download all of the files above and install them into the craepas-cli/ folder under your skills directory — do not install only SKILL.md.

After installation, complete the setup: I will provide the API key. First set the CLI_API_KEY environment variable, then run setup.sh --profile default (it is an interactive script; with the environment variable set it skips the prompt and verifies the connection directly; the service URL defaults to https://api.craepas.ai, no need to fill it in). The configuration is written to ~/.craepas/profiles/default.json. Finally, call GET /api/cli/apidoc to discover the current API.

Use default for the first connection; ask for a new profile name when adding a workspace. Never overwrite a name belonging to another connection. Scope environment variables to the setup command; afterwards select the saved profile explicitly for verification.

Appendix 1: Live API documentation

Call GET /api/cli/apidoc for the deployed endpoints, parameters, responses and pagination rules. The skill handles connection and API discovery.

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

Appendix 2: Typical scenarios

After setup, give these instructions to your external agent. Start with GET /api/cli/apidoc for the deployed API contract. Replace example workitems, files and times with your own.

Scenario 1: Find workspace or workitem context

The key is bound to one workspace. Read the workspace and existing workitems before selecting workItemId. Search without workItemId includes child workitems; specifying it narrows the scope. Search covers indexed metadata and summaries, and indexing may lag.

Read the live apidoc, confirm the workspace and list existing workitems. Find the workItemId for “Monthly business analysis”, search that workitem for “sales daily report”, and list sources and summaries. Download originals when needed for verification.

Scenario 2: Upload a batch and organize it with a manifest

Upload files and their manifest to the same scope. Follow apidoc: finalize a successful direct upload with complete; a successful proxy upload is already complete. Save returned objectKey values rather than inventing paths. Record batchId, objectKey / originalName and processing instructions. Matching filenames do not imply replacement or identify a batch.

Upload files from local ./reports/ to the confirmed workitem 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.

Scenario 3: Delegate work remotely and retrieve results

For immediate work, create a task with POST /api/cli/tasks; no conversation or schedule is needed. Provide title and instruction; omit workItemId for workspace scope or supply it for workitem scope. Search existing context and discover available skills, connectors and cloud browsers as needed, then include actual resource identifiers and requirements in the instruction. Save the returned runId, query task details until terminal, read result for outcomes and artifacts, and download through Drive.

Confirm the workspace and workitem, 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.

Scenario 4: Create and maintain schedules

POST /api/cli/scheduled-tasks creates an active definition that executes automatically when due. Omit workItemId for workspace scope or supply it for workitem scope. Rules support once, interval, daily and weekly; specify timezone for recurring wall-clock times. PATCH /api/cli/scheduled-tasks/{id} accepts a complete form or a status-only pause/enable update. Full-form edits must include the desired workItemId; omitting it or sending null selects workspace root. A different valid workitem in the same workspace is allowed. Status-only edits retain scope.

Read apidoc and confirm the uploaded manifest. Create a one-time schedule in that same workitem using my specified future time and timezone, include the manifest’s actual location and processing requirements in the task instruction, process its files and produce a Chinese daily report. Return definition ID, scope, status and next run time. Ask me for a concrete time if missing. Read details before later edits and include the desired workItemId in full forms; pause with {"status":"paused"} and resume with {"status":"active"}.

Scenario 5: Query scheduled task execution records and download artifacts

GET /api/cli/scheduled-tasks/{id}/runs provides shared history with limit / offset pagination. GET /api/cli/scheduled-tasks/{id}/runs/{runId} reads the key user’s run status; another user’s run returns 404. After completion, list Drive artifacts in the same scope and download by artifactId. Uploads and artifacts have separate lists; omitting workItemId lists only the workspace root.

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 workitem and download the daily report. If the association cannot be confirmed, explain instead of selecting an unrelated report.

Permissions and limits: Workspace / WorkItem are read-only. Direct delegation requires current Agent permission and AI quota. Schedule writes follow current permissions and creator/admin rules. Use tasks for immediate work and schedules for future or recurring work. CLI does not provide schedule run-now, deletion or notification resend. A single-batch manifest suits a single execution; recurring tasks need explicit rules for selecting each period’s inputs rather than treating a fixed manifest as the latest batch.