CLI Options

Reference for OctoMY™ command-line arguments and options.

Pro Tip

For testing, the --auto-delivery --auto-discovery flags are invaluable - they skip the interactive birth ceremony and automatically accept discovered peers. Combine with --personality TestBot to create isolated test environments without affecting your production nodes.

Overview

OctoMY™ applications accept command-line options for configuration:

Common options

Options available for all OctoMY™ applications:

Help and version

Network options

Identity options

Logging options

Agent-specific options

Options for the Agent (robot) application:

Hardware options

Behavior options

Connection options

Remote-specific options

Options for the Remote (controller) application:

Input options

Display options

Hub-specific options

Options for the Hub (fleet management) application:

Server options

Storage options

MockNode options

Options for the MockNode testing application:

Personality options

Automation options

Testing options

Usage examples

Basic usage

# Start Agent on custom port
octomy-agent --port 9000

# Start Agent with named personality
octomy-agent --personality MyRobot

# Start Agent with verbose logging
octomy-agent --log-level debug --verbose

Network configuration

# Bind to specific interface
octomy-agent --address 192.168.1.100 --port 8124

# Disable discovery (manual connections only)
octomy-agent --no-discovery

# Custom discovery interval
octomy-agent --discovery-interval 10000

Development and testing

# Run without hardware
octomy-agent --no-hardware

# Auto-complete pairing for testing
octomy-agent --auto-delivery --auto-discovery

# Log to file
octomy-agent --log-file /tmp/octomy.log --log-level debug

MockNode testing

# Create test Agent
mocknode --personality TestAgent --node-type agent

# Create test Remote with auto-pairing
mocknode --personality TestRemote --node-type remote \
         --auto-delivery --auto-discovery

# Run automation script
mocknode --personality ScriptTest --script test_scenario.txt

Graphics and diagnostics options

Every OctoMY application accepts these before or after its own options. They are flags, not environment variables. The graphics ones are explained in Graphics backend. The diagnostic ones are explained in Collect useful logs.

Qt platform options

Standard Qt options are also available:

Display options

Common platforms

Examples

# Force Wayland
octomy-agent -platform wayland

# Use custom style
octomy-agent -style fusion

# Headless mode
octomy-agent -platform offscreen

Environment variable overrides

Environment variables can override command-line options:

Precedence

1. Command-line options (highest)
2. Environment variables
3. Settings file
4. Default values (lowest)

Example

# Environment variable
export OCTOMY_PORT=9000

# Command-line overrides environment
octomy-agent --port 9500  # Uses 9500, not 9000

Exit codes

OctoMY™ applications return standard exit codes:

Checking exit code

octomy-agent --personality Test
EXIT_CODE=$?

if [ $EXIT_CODE -eq 0 ]; then
    echo "Exited normally"
elif [ $EXIT_CODE -eq 2 ]; then
    echo "Invalid arguments"
else
    echo "Error: $EXIT_CODE"
fi

Configuration file integration

Command-line options interact with configuration files:

Loading order

Persisting options

Command-line options are not automatically saved. To persist:

# Run with option
octomy-agent --port 9000

# Save to settings file manually
# Or use settings UI to make permanent

Script integration

Bash script

#!/bin/bash
# start_agent.sh - Start Agent with custom configuration

PERSONALITY="${1:-DefaultAgent}"
PORT="${2:-8124}"
LOG_LEVEL="${3:-info}"

exec octomy-agent \
    --personality "$PERSONALITY" \
    --port "$PORT" \
    --log-level "$LOG_LEVEL" \
    --auto-delivery

Systemd service

# /etc/systemd/system/octomy-agent.service
[Unit]
Description=OctoMY Agent
After=network.target

[Service]
Type=simple
User=robot
ExecStart=/usr/bin/octomy-agent \
    --personality ProductionAgent \
    --port 8124 \
    --log-file /var/log/octomy/agent.log \
    --log-level info
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Docker

FROM ubuntu:22.04

COPY octomy-agent /usr/bin/

ENTRYPOINT ["octomy-agent"]
CMD ["--personality", "DockerAgent", "--port", "8124"]

# Run with custom options
docker run octomy-agent --personality CustomAgent --port 9000

Debugging options

Verbose output

# Maximum verbosity
octomy-agent --log-level debug --verbose

# Output includes:
# - Configuration loading
# - Network events
# - Handshake details
# - Courier activity

Dry run

# Check configuration without starting
octomy-agent --personality Test --dry-run
# Outputs: Configuration valid, would start with...

Version information

octomy-agent --version
# OctoMY Agent 1.0.0
# Qt 6.8.0
# Built: 2024-01-15

Option reference table

Complete option reference: