How to Use RoboNeo CLI

RoboNeo command-line tool can be used independently in the terminal, or it can call RoboNeo capabilities through Lobster to implement local capabilities such as conversing with AI Agents, creating chat rooms, and downloading results.

Requirements

• Node.js >= 18
• npm

Installation

Install globally to use roboneo from any directory:

npm install -g roboneo-cli

The package name is roboneo-cli, and the executable command is roboneo.

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

Configuration

Required

After logging in, click your avatar and select "CLI Settings" to obtain your personal access token.

An access token is required and follows this priority: environment variable > credentials.json.

export ROBONEO_ACCESS_KEY="your-access-token"

You can also write it to the local credentials file at ~/.roboneo/credentials.json:

roboneo config access_token "<your-access-token>"

Commands that require authentication will fail if neither the environment variable nor the local credentials file is configured.

Global Options

roboneo --help
roboneo help

roboneo help prints a built-in compact English usage guide without depending on the README or skill files.

Command Overview

Usage Notes

• Start by sending a message with chat
• Then use history-detail to retrieve updates and results
• If next_action.action is recharge, show next_action.extra.recharge.content and direct the user to next_action.extra.recharge.url; after the recharge is complete, continue with a new chat
• If next_action.action is reply, continue with reply
• Generated outputs are listed under artifacts and can be saved locally with download

Common Examples

Show current config with a masked token:

roboneo config list

Validate the token if needed:

roboneo user-info

Create a room and start chatting:

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

Chat directly and auto-create a room if needed:

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

Create a team room and chat in team mode:

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 the previous topic" --room-id "<room_id>"

Check for updates and results:

# Full fetch (single/team mode is detected automatically)
roboneo history-detail -r "<room_id>"

# Incremental fetch (returns only messages with seq > N)
roboneo history-detail -r "<room_id>" --after-seq 3

Respond to AI follow-up requests while using history-detail to monitor updates:

# Reply to a follow-up prompt
roboneo reply -r "<room_id>" --last-request-id BLOCK_xxx -p "Provide the requested details"

# Reply with an attachment
roboneo reply -r "<room_id>" --last-request-id BLOCK_xxx -p "Use this image" --image-file ./photo.png

# Reply to an option_request by selecting options
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 "Provide the requested details"

Download assets:

# Download all room assets to the current directory
roboneo download -r "<room_id>"

# Specify an output directory
roboneo download -r "<room_id>" -o ./output

Subcommand Details

create-room

chat

reply

history-detail

Common fields in history-detail:

• next_action: the next step to take
  • poll: processing is still in progress; keep polling
  • recharge: the user must recharge first; extra.recharge.url is WEB_URL + /home?modal=purchase, and extra.recharge.content is the message to display. After recharging, continue with a new chat
  • reply: user input or option selection is required
  • done: the interaction is complete
• artifacts: generated outputs
• items: conversation and process messages
• max_seq: use this value in the next incremental request with --after-seq

Example recharge response:

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

The actual value of extra.recharge.url depends on the environment and is derived from WEB_URL.

download

Attachment Rules

• Images and videos can be combined, up to 2 images plus 1 video
• If no video is attached, up to 10 images are supported
• At most 1 file is supported
• Files cannot be used together with images or videos
• URLs and local paths can be mixed within the same attachment type
• Attachment type is inferred from the file extension for both URLs and local paths
• 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 Flow

1. Set ROBONEO_ACCESS_KEY
2. Optionally confirm the token with user-info or config list
3. Start a conversation with chat -p "your question"; the CLI creates a room automatically when needed, or you can run create-room first
4. Use history-detail -r ROOM_ID to retrieve updates and results
5. If next_action is recharge, ask the user to recharge first, then resume with a new chat
6. If next_action is reply, use reply to answer the follow-up or select options
7. If next_action is poll or reply, continue calling history-detail until next_action becomes done
8. Use download -r ROOM_ID -o ./output to save generated outputs locally
9. Use history or history-detail to review previous conversations when needed

Local State

create-room and chat when it creates a room automatically store room-related state in ~/.roboneo/storage.json. By default, chat uses the most recently created room and creates one automatically if none exists. You can override this behavior with --room-id.

License

MIT