CLI Commands

OrpheAgent provides a comprehensive set of command-line interface (CLI) commands to manage, configure, and operate the agent. Below is a detailed list of the available commands, their functionalities, and supported options.

Start the Agent

Use the up command to start the OrpheAgent:

orphe-agent up

Alias: orphe-agent u

Options:

• -d, --debug: Enable debug mode to provide detailed logs for troubleshooting.
• -f, --foreground: Run the agent in the foreground instead of as a daemon.

Stop the Agent

Use the down command to stop the OrpheAgent:

orphe-agent down

Alias: orphe-agent d

This command stops the systemd service when it is active. If the service is not active, it sends a shutdown event to the Agent running in the foreground.

Restart the Agent

Use the restart command to restart the OrpheAgent:

orphe-agent restart

Alias: orphe-agent r

This command stops the currently running agent and starts it again. It is functionally equivalent to running orphe-agent down followed by orphe-agent up.

Configuration Management

Use the config command to manage configurations. Each option can be configured individually. Note that any changes will only take effect after executing the save action.

orphe-agent config ACTION

Alias: orphe-agent c ACTION

Supported actions:

• save: Save the current configuration to the default configuration file.
• clean: Clear the existing configuration and restore the default values.
• show: Display the current configuration in a human-readable format.

Options:

• -p, --provision-key: Specify the provision key (e.g., 12D3KooWS).
• -n, --host-name: Set the host name (e.g., orphe-agent).
• -h, --mgmt-port-http: Set the HTTP management port (default: 0). Use none to disable HTTP management.
• -s, --mgmt-port-https: Set the HTTPS management port (default: 0). Use none to disable HTTPS management.
• -c, --controlplane-tun-port: Set the control plane tunnel port (default: 0).
• -d, --dataplane-tun-port: Set the data plane tunnel port (default: 0).

!TIP Use 0 to let the system assign a random port. HTTP and HTTPS management cannot both be set to none. Every configured non-zero port must be unique and available.

Examples:

• Show the current configuration:

  orphe-agent config show
  

  Copy code
• Save a configuration with a custom provision key and host name:

  orphe-agent config save --provision-key 12D3KooWS --host-name my-agent
  

  Copy code
• Disable HTTP management and set the HTTPS management port to 443:

  orphe-agent config save --mgmt-port-http none --mgmt-port-https 443
  

  Copy code
• Reset the configuration to the default values:

  orphe-agent config clean
  

  Copy code

Profile Management

Use the profile command to manage multiple configuration profiles:

orphe-agent profile ACTION

Alias: orphe-agent pf ACTION

Supported actions:

• list: Display all available profiles and their current usage status.
• create: Create a new profile with a specified name.
• delete: Delete an existing profile.
• use: Switch to and activate a profile, then reload OrpheAgent with the selected profile.

Options:

• -n, --name: The name of the profile (required for the create, delete, and use actions).

Examples:

• List all profiles:

  orphe-agent profile list
  

  Copy code
• Create a new profile named "production":

  orphe-agent profile create -n production
  

  Copy code
• Switch to the "production" profile:

  orphe-agent profile use -n production
  

  Copy code
• Delete the "staging" profile:

  orphe-agent profile delete -n staging
  

  Copy code

!NOTE The default profile cannot be deleted. Switch to another profile before deleting the current profile. Deletion requires confirmation; enter yes when prompted.

Provision Management

Use the provision command to configure discovery settings for the provisioning process:

orphe-agent provision ACTION

Alias: orphe-agent p ACTION

Supported actions:

• save: Save the current provision configuration.
• clean: Clear the provision configuration and restore the default values.
• show: Display the current provision configuration in a readable format.

Options:

• -x, --multicast: Enable or disable Multicast discovery (true or false).
• -m, --mdns: Enable or disable MDNS discovery (true or false).
• -r, --relay: Enable or disable Relay discovery (true or false).

!NOTE Only true or false (case-insensitive) are accepted as arguments for each boolean flag.

Examples:

• Show current provision settings:

  orphe-agent provision show
  

  Copy code
• Enable Multicast and MDNS, and disable Relay:

  orphe-agent provision save --multicast true --mdns true --relay false
  

  Copy code
• Reset the provision configuration to its defaults:

  orphe-agent provision clean
  

  Copy code

Control Plane P2P Management

Use the control-plane-p2p command to configure P2P settings for the control plane:

orphe-agent control-plane-p2p ACTION

Alias: orphe-agent cp-p2p ACTION

Supported actions:

• save: Save the current P2P settings.
• show: Display the current P2P configuration.
• clean: Reset the P2P configuration to the default values.

Options:

• -d, --dht: Enable or disable DHT Discover (true or false).
• -u, --udp-hole-punch: Enable or disable UDP Hole Punch (true or false).
• -r, --relay: Enable or disable Relay Transport (true or false).

!NOTE Only true or false (case-insensitive) are accepted as arguments for each boolean flag.

Examples:

• Show current P2P settings:

  orphe-agent control-plane-p2p show
  

  Copy code
• Enable DHT and Relay, and disable UDP Hole Punch:

  orphe-agent control-plane-p2p save --dht true --relay true --udp-hole-punch false
  

  Copy code
• Reset the P2P configuration to its defaults:

  orphe-agent control-plane-p2p clean
  

  Copy code

Data Plane P2P Management

Use the dataplane-p2p command to configure P2P settings for the data plane:

orphe-agent dataplane-p2p ACTION

Alias: orphe-agent dp-p2p ACTION

Supported actions:

• save: Save the current P2P settings.
• show: Display the current P2P configuration.
• clean: Reset the P2P configuration to default values.
• up: Bring up the data plane.
• down: Bring down the data plane.

Options:

• -d, --dht: Enable or disable DHT Discover (true or false).
• -u, --udp-hole-punch: Enable or disable UDP Hole Punch (true or false).
• -r, --relay: Enable or disable Relay Transport (true or false).
• -b, --dataplane-on-boot: Enable or disable Data Plane on boot (true or false).
• -s, --snat: Enable or disable SNAT (Source Network Address Translation) for data plane traffic (true or false).
• -t, --tun-mode: Set the data plane tunnel mode to either low_latency or high_throughput (default: high_throughput).

!NOTE Only true or false (case-insensitive) are accepted for boolean flags.

Examples:

• Show current P2P settings:

  orphe-agent dataplane-p2p show
  

  Copy code
• Enable DHT and Relay, and disable UDP Hole Punch:

  orphe-agent dataplane-p2p save --dht true --relay true --udp-hole-punch false
  

  Copy code
• Set the data plane tunnel mode to low latency:

  orphe-agent dataplane-p2p save --tun-mode low_latency
  

  Copy code
• Enable SNAT for data plane traffic:

  orphe-agent dataplane-p2p save --snat true
  

  Copy code
• Bring up the data plane:

  orphe-agent dataplane-p2p up
  

  Copy code
• Bring down the data plane:

  orphe-agent dataplane-p2p down
  

  Copy code
• Reset P2P configuration to default:

  orphe-agent dataplane-p2p clean
  

  Copy code

System Check

Run the system-check command to perform a system compatibility check for OrpheAgent:

orphe-agent system-check

Alias: orphe-agent sc

This command verifies whether the host system supports the required features for the agent to function correctly.

Status Command

Use the status command to check the operational status of OrpheAgent:

orphe-agent status

Alias: orphe-agent s

Options:

• -d, --dp-link-status: Show the link status of the data plane.
• -c, --cp-link-status: Show the link status of the control plane.
• -n, --nat-type: Show the detected NAT type and P2P compatibility description.

Without options, this command displays the service, Control Plane link, and Data Plane link status. With an option, it displays only the requested information. Link status includes metrics such as latency, jitter, and data rate.

Examples:

orphe-agent status
orphe-agent status --dp-link-status
orphe-agent status --cp-link-status
orphe-agent status --nat-type

Help Command

Use the help command to retrieve usage information for a specific subcommand:

orphe-agent help

Alias: orphe-agent h

This command displays detailed usage instructions and available options for the specified subcommand. For example, to get help for the up command:

orphe-agent help up

Version Command

Use the version command to print the currently installed version of the OrpheAgent CLI:

orphe-agent version

Alias: orphe-agent v

This command outputs the version information of the installed OrpheAgent binary, which is highly useful for troubleshooting and verifying deployments.

Update Command

Use the update command to check for available updates and install the latest version of OrpheAgent:

orphe-agent update

Alias: orphe-agent upd

This command checks for a newer version of OrpheAgent, downloads the update, and installs it automatically.

Options:

• -c, --check: Only check for updates without installing them.

Examples:

• Check for updates and install them immediately:

  orphe-agent update
  

  Copy code
• Only check if a new update is available:

  orphe-agent update --check
  

  Copy code

More Command Information

For additional guidance, refer to the project documentation or run orphe-agent help to view detailed command descriptions.