How to Use RoboNeo CLI

RoboNeo command line tool: chat with AI Agents, create rooms, dispatch tasks, poll results, reply to follow-ups, upload attachments, and download artifacts.

Prerequisites

• Node.js >= 18
• npm

Installation

After global installation, you can use the roboneo command in any directory:

npm install -g @meitu/roboneo-cli@alpha --registry http://npm.meitu-int.com

The package name remains @meitu/roboneo-cli; only the executable command is changed to roboneo.

For local development, execute npm run build:pre from the repository root, then use npm start or node bin/roboneo-cli.js.

Configuration

Required

After loggin in, click on your profile, and select 'API Key' to get your access token:

Access token (consistent with login state). Priority: Environment variables > credentials.json.

export ROBONEO_ACCESS_KEY="Your access token"

Alternatively, write to the local credentials file (~/.roboneo/credentials.json):

roboneo config access_token "<Your access token>"

Commands requiring a token will fail if neither the environment variable nor the local credentials file is configured.

Global Options

roboneo --help

Command Summary

Usage Instructions

• First, use chat to submit questions or tasks
• Next, use history-detail to check progress and results
• If next_action.action is recharge, display next_action.extra.recharge.content and redirect to next_action.extra.recharge.url; after recharging, continue polling history-detail
• If next_action.action is reply, use reply to continue
• Artifacts can be directly fetched from artifacts and saved locally using download

Common Examples

View configuration (token is masked):

roboneo config list

Verify token (optional):

roboneo user-info

Create a room and chat:

roboneo create-room
roboneo chat -p "Hello, introduce yourself."

Direct chat (automatically creates a room if none exists):

roboneo chat -p "Help me generate a milk tea poster."

Create a team room and chat:

roboneo create-room --mode team
roboneo chat -p "Help me generate an image and a video" --mode team

Chat in a specific room:

roboneo chat -p "Continue our last topic" --room-id "<room_id>"

Poll task results:

# Full fetch (auto-detects single/team mode)
roboneo history-detail -r "<room_id>"
# Incremental fetch (returns only new messages where seq > N)
roboneo history-detail -r "<room_id>" --after-seq 3

Reply to AI follow-ups (used with history-detail polling):

# Reply to request type
roboneo reply -r "<room_id>" --last-request-id BLOCK_xxx -p "Reply content"
# Reply to request type with attachments
roboneo reply -r "<room_id>" --last-request-id BLOCK_xxx -p "Use this image" --image-file ./photo.png
# Reply to option_request type (select an option)
roboneo reply -r "<room_id>" --last-request-id BLOCK_xxx -p "" --select-option-ids '[["opt_1"]]'
# Reply in team mode
roboneo reply -r "<room_id>" --mode team --task-id TASK_ID --sub-task-id SUB_TASK_ID --last-request-id BLOCK_xxx -p "Reply content"

Download artifacts:

# Download all artifacts in the room to the current directory
roboneo download -r "<room_id>"
# Specify output directory
roboneo download -r "<room_id>" -o ./output

Subcommand Details

create-room

chat

reply

history-detail

Common history-detail fields:

• next_action: The next step to take
  • poll: Task incomplete; continue polling
  • recharge: Triggers top-up prompt, asking user to recharge first (extra.recharge.url = WEB_URL + /home?modal=purchase, extra.recharge.content displays copy)
  • reply: Requires user to reply to follow-ups or select an option
  • done: Process complete
• artifacts: Generated artifacts list
• items: Dialogue and process messages
• max_seq: Used for the next incremental fetch (--after-seq)

recharge response example:

{
  "next_action": {
    "action": "recharge",
    "items": [{ "type": "guide_purchase", "content": "Insufficient credits. Upgrade to a premium membership to continue." }],
    "extra": {
      "recharge": {
        "url": "https://pre.roboneo.com/home?modal=purchase",
        "content": "Insufficient credits. Upgrade to a premium membership to continue."
      }
    }
  }
}

The actual value of extra.recharge.url varies by environment (concatenated from WEB_URL).

download

Attachment Rules

• Images and videos can be combined, supporting a maximum of 2 images and 1 video
• If no video is included, up to 10 images are supported
• Up to 1 file is supported
• Files cannot be combined with images/videos
• URLs and local paths can be mixed for the same file type
• File type is determined by extension for both URLs and local paths
• Local file size limits: Images ≤ 20 MB, Videos ≤ 500 MB, Audio ≤ 500 MB, Other files ≤ 10 MB

Attachment examples:

roboneo chat -p "Analyze these images" \\
  --image-url https://example.com/a.jpg https://example.com/b.png

roboneo chat -p "Analyze these inputs" \\
  --image-url https://example.com/a.jpg \\
  --image-file ./local.png

roboneo chat -p "Analyze this video with two images" \\
  --video-file ./demo.mp4 \\
  --image-file ./a.png ./b.jpg

roboneo chat -p "Summarize this document" \\
  --file ./spec.pdf

Recommended Workflow

1. Set up ROBONEO_ACCESS_KEY
2. (Optional) Verify your token using user-info or config list
3. Chat using chat -p "Your prompt" (auto-creates a room if none exists, or use create-room manually)
4. Poll for results using history-detail -r ROOM_ID
5. If next_action is recharge, prompt the user to top up; continue polling after successful top-up
6. If next_action is reply, use reply to respond to follow-ups or select options
7. Continue polling history-detail until next_action is done
8. Download generated artifacts to a local directory using download -r ROOM_ID -o ./output
9. View history records when needed using history / history-detail

Local State

Commands like create-room or chat (during auto-creation) will save room details in the user's directory (default path: ~/.roboneo/storage.json). The chat command relies on the most recently created room by default and auto-creates one if none exists. You can also manually specify an ID with --room-id.

License

ISC