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

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: