CodeM Sandbox CLI

Agent-facing CLIs that wrap CodeM sandbox proxy endpoints.

Both CLIs authenticate with the sandbox-injected CODEM_TOKEN and never ask the agent for Meego or Lark app id, app secret, plugin token, or tenant token.

Install

npm i -g @codemuniverse/codem-sandbox-cli --registry=https://registry.npmmirror.com

Environment

• CODEM_TOKEN: required CodeM identity token.
• CODEM_BASE_URL: CodeM server origin. Defaults to https://codem.feishu.cn.
• CODEM_PROXY_BASE_URL: optional override for this CLI.
• CODEM_BASE_HTTP_URL: compatibility alias for the CodeM server URL.
• CODEM_DISPATCH_ID: optional task context for stricter Meegle write checks.
• AI_EVENT_TYPE: Meego AI event type for sandbox-meegle-cli. Values starting with 80 use AI node flow, values starting with 82 use status flow. --ai-event-type overrides this env var.
• CODEM_AI_ENTITY_ID: optional AI entity id. It is required by write commands if --ai-entity-id is not passed. The proxy forwards it to Meego operation OpenAPI requests as x-ai-entity-id; query commands do not send this header.
• CODEM_AI_ENTITY_STATUS: optional status for ai-node done; defaults to done.

--base-url may be either an origin such as https://codem.feishu.cn or a /goapi/codem prefix URL.

Meegle Commands

AI_EVENT_TYPE=8007 \
sandbox-meegle-cli workitem get \
  --project-key proj \
  --work-item-type story \
  --work-item-id 123 \
  --fields '["name","status"]'

AI_EVENT_TYPE=8207 \
sandbox-meegle-cli workflow transition \
  --project-key proj \
  --work-item-type story \
  --work-item-id 123 \
  --ai-entity-id ai_entity_1 \
  --field-json '{"field_key":"status","field_value":"done"}'

sandbox-meegle-cli ai-node done \
  --project-key proj \
  --work-item-id 123 \
  --state-key state_ai_current \
  --ai-entity-id ai_entity_1

UUID=$(sandbox-meegle-cli workitem get \
  --project-key proj \
  --work-item-type story \
  --work-item-id 123 \
  --fields '["files_field"]' \
  --data-only | jq -r '.items[0].fields.files_field[0].uuid')

sandbox-meegle-cli attachment +download \
  --project-key proj \
  --work-item-type story \
  --work-item-id 123 \
  --uuid "$UUID" \
  --output ./a.pdf \
  --overwrite

All commands print JSON. Pass --data-only to print the proxy response data field only.

Meegle Parameters

Common parameters:

• --project-key: required Meego project key or space simple name.
• --dispatch-id / CODEM_DISPATCH_ID: optional task context. When present, the proxy additionally checks that the token, cluster, Meego project, and source work item match that dispatch. When omitted, writes are authorized by the CODEM_TOKEN tenant/project/cluster scope plus the bound Meego space.
• --ai-event-type / AI_EVENT_TYPE: Meego AI event type. Prefix 80 means AI node flow; prefix 82 means status flow. Callers only pass the event type; CodeM chooses the server-side Meego credentials and headers.
• --ai-entity-id / CODEM_AI_ENTITY_ID: required for write commands (workflow transition and ai-node done). The proxy sends it as x-ai-entity-id on Meego operation OpenAPI requests. workitem get does not send x-ai-entity-id.
• --state-key / --node-id: optional current-node/current-state override. For AI_EVENT_TYPE=80* node flow, omit it to let the proxy use the existing auto-selected current_nodes[0].id; pass it when a work item has multiple current nodes and you need to choose the exact AI node. For 82* status flow, it is the current work_item_status.state_key, not the target state.
• --node-uuid: optional AI node uuid for 80* node flow, alternative to --state-key / --node-id.
• --transition-id: optional override for workflow transition when AI_EVENT_TYPE starts with 82. The proxy normally queries workflow detail with flow_type=1, finds the connections[] record whose source_state_key equals the current state key, and uses that record's transition_id. If supplied, it must be the next-state connection id as int64, not a state key such as RESOLVED.

Command-specific parameters:

• workitem get: requires --work-item-type and --work-item-id; optional --fields, --expand-json, and --ai-event-type.
• workflow transition: requires --work-item-type, --work-item-id, --ai-entity-id, and --ai-event-type or AI_EVENT_TYPE. Prefix 80 runs AI node flow; prefix 82 runs status flow. For 80*, the proxy uses the supplied --state-key / --node-id or --node-uuid when present; otherwise it keeps the existing auto behavior and uses the first node id from current_nodes. It then calls POST /open_api/ai_node/edit with status=done and POST /open_api/ai_node/confirm. For 82*, the proxy uses a supplied --transition-id first; if omitted, it queries current state_key and workflow connections to resolve transition_id, then calls Meego state transition POST /open_api/:project_key/workflow/:work_item_type_key/:work_item_id/node/state_change, then calls PUT /open_api/ai_entity/update (OAPIUpdateAiEntity) with project_key and update_ai_entity_param[0] carrying entity_id=<ai_entity_id> and status=done.
• ai-node done: requires --work-item-id, --ai-entity-id, and --state-key/--node-id (or --node-uuid). This is also the current AI node state key. Optional --status defaults to done.
• attachment +download: requires --project-key, --work-item-type, --work-item-id, --uuid/--file-uuid, and --output. Get the uuid from workitem get; the proxy rejects requests without uuid. Rich-text attachments are returned under multi_texts, and attachment fields whose type is multi_file also include file uuid. The proxy calls Meego POST /open_api/:project_key/work_item/:work_item_type_key/:work_item_id/file/download with body {"uuid":"..."} and streams the binary response back to the CLI. The CLI writes to <output>.partial and atomically renames to --output. Pass --overwrite to replace an existing file.

workitem get always sends expand.need_multi_text=true to Meego OpenAPI from the proxy, even when the caller omits --expand-json, so rich-text and attachment references needed for downloads can be returned by Meego.

ai-node done calls Meego POST /open_api/ai_node/edit through the CodeM proxy and sends this OpenAPI body shape:

{
  "project_key": "proj",
  "work_item_id": "123",
  "state_key": "state_ai_current",
  "status": "done"
}

The CodeM proxy obtains Meego plugin credentials, plugin tokens, configured headers, hosts, and configured Meego user_key server-side. The sandbox process only supplies CODEM_TOKEN and operation parameters. sandbox-meegle-cli does not accept or forward a caller-provided Meego user key; if the selected TCC block has no user_key, the server reports the Meego proxy as unavailable.

Server-side Meego identity selection is hidden behind the proxy. Operation commands add x-ai-entity-id; query commands do not.

Meegle Proxy Endpoints

• POST /goapi/codem/proxy/openapi/work_item/detail
• POST /goapi/codem/proxy/openapi/work_item/state_change
• POST /goapi/codem/proxy/openapi/ai_node/done
• POST /goapi/codem/proxy/openapi/attachment/download

Lark Knowledge Commands

sandbox-lark-cli follows the official lark-cli docs +... command shape where the operation is equivalent. All Lark commands authenticate only with CODEM_TOKEN; the server exchanges the configured Lark app id/secret for a tenant access token and uses app identity to call Lark OpenAPI.

The document scope is always the knowledge list bound in the CodeM space for the token's project. The agent cannot search or read tenant-wide documents. Summary search calls Feishu Search v2 POST /open-apis/search/v2/doc_wiki/search and then the proxy filters results back to the bound knowledge token/URL set. Content search reads bound document raw text with app identity and returns keyword snippets. docs +fetch and docs +search-content resolve the CodeM-bound document and read Feishu Docx raw_content; the returned document block is populated from the CodeM binding plus resolved document id, without an extra live document metadata lookup. The CodeM project key is decoded server-side from CODEM_TOKEN; callers do not pass --project-key for sandbox-lark-cli.

Lark Recommended Workflow

1. Search the bound knowledge scope and get candidate documents. The response returns knowledge_key at data.items[].knowledge.knowledge_key.

sandbox-lark-cli docs +search \
  --query design \
  --page-size 20

The summary result also includes highlighted title, highlighted summary, document URL, and owner metadata. Pick the document whose summary looks relevant and keep its knowledge_key.

2. Search exact body snippets. Without --knowledge-key, this scans all readable documents bound to the CodeM space. With --knowledge-key, it limits matching to the selected document. The response also carries data.items[].knowledge.knowledge_key, so agents can still fetch the selected document after reading snippets.

sandbox-lark-cli docs +search-content \
  --query "rollback strategy" \
  --page-size 20

sandbox-lark-cli docs +search-content \
  --query "rollback strategy" \
  --knowledge-key kn_1234567890 \
  --context-chars 160 \
  --matches-per-document 3

3. Fetch the full text of one bound document using the knowledge_key returned by docs +search or docs +search-content.

sandbox-lark-cli docs +fetch \
  --knowledge-key kn_1234567890

For agent workflows that only need text:

sandbox-lark-cli docs +fetch \
  --knowledge-key kn_1234567890 \
  --content-only

Lark Parameters

• --query: required for docs +search and docs +search-content.
• --page-size: maximum summary results or content matches. Summary search is capped by the server and Feishu Search v2 page size.
• --page-token: continue docs +search from the previous summary search response.
• --knowledge-key: required for docs +fetch; optional for docs +search-content to limit full-text matching to one bound document.
• --context-chars: content-search context characters around each hit.
• --matches-per-document: maximum content-search hits per document.
• --content-only: for docs +fetch, print only document plain text.
• --data-only: print only the proxy data field.

Lark Proxy Endpoints

• POST /goapi/codem/proxy/lark/knowledge/search
• POST /goapi/codem/proxy/lark/knowledge/read
• POST /goapi/codem/proxy/lark/knowledge/fulltext_search