Adapnex CLI Reference Guide

The Adapnex CLI (adapnex) is the primary interface for managing your Industrial Software Engineering workflow. It bridges the gap between modern DevOps practices and physical industrial hardware, allowing you to deploy deterministic C++ applications to Real-Time Linux targets without proprietary IDEs.

Installation

Install the Adapnex CLI for your platform:

  • macOS / Linux

  • Windows

Run the following command in your terminal:

curl -fsSL https://download.adapnex.com/install.sh | bash

Run the following command in PowerShell:

irm https://download.adapnex.com/install.ps1 | iex

Once installed, verify the installation:

adapnex version

Authentication

Before interacting with your devices, you must authenticate your local machine with the Adapnex Cloud.

Login

Initiates an OAuth2 device flow to securely link your CLI session to your account. This eliminates the need for manual API key management on developer workstations.

adapnex login
Example: Authenticate using the device flow
$ adapnex login

Action required:
1. Please open this URL: https://adapnex-cloud.us.auth0.com/activate
2. Enter the following code: XXXX-XXXX

Successfully authenticated!

Whoami

Displays the user account currently authenticated in the Adapnex CLI session.

adapnex whoami
Example: Display current user information
$ adapnex whoami
Fred Nerk <[email protected]> (Google)

Application Development

The Adapnex SDK for C++ is based on the CMake build system. The build command simplifies the compilation process by invoking CMake with the correct target and toolchain configurations required for the Adapnex SDK.

Build application

Compiles your application for a specific target hardware. This command must be executed in the same directory as the root CMakeLists.txt of your project.

adapnex build <device> [<targets>...] [flags]
Argument Description

<device>

The hardware target identifier (e.g., bnr_x20eds410, wago_cc100) or a registered device (e.g., oven_control, assembly_line). Use generic to target the host device (e.g. for testing and simulation).

<targets>

(Optional) The names of specific CMake targets to build. If omitted, all targets are built.
Flag Description

--sdk-version string

Version of the Adapnex SDK to use (default "latest").
Example: Build the conveyor_controller target for a WAGO CC100.
adapnex build wago_cc100 conveyor_controller

Run Tests

Builds and runs unit tests defined in your project using the adapnex_tests() command.

adapnex test [flags]
Flag Description

--sdk-version string

Version of the Adapnex SDK to use (default "latest").

Application Deployment

The core of the Adapnex CLI is the ability to manage the full lifecycle of Real-Time Linux applications. These commands handle compilation artifacts, versioning, and process control.

Run application

Downloads and executes a binary application on a target device. The CLI automatically handles versioning by creating a timestamped directory for every deployment, ensuring atomic updates.

adapnex app run <device> <executable> [<extra-files>...] [flags]
Argument Description

<device>

Target device ID or alias.

<executable>

Name of a CMake target defined using the adapnex_executable() command or path to a local binary.

<extra-files>

(Optional) Additional configuration files or assets to download with the binary. These will be placed in the same directory as the executable on the target.
Flag Description

--app string

Assign a logical name to the application (default "main"). Useful for running multiple processes on one controller.

--debug

Starts the application in a suspended state, waiting for a debugger to attach.

--detached

Deploys the application and returns control to the terminal immediately, without attaching to STDOUT and STDERR.

--once

Disables the automatic restart policy. Useful for one-off scripts or diagnostic tools that should not restart on exit or reboot.

--port int

Local port to listen on for the debugger connection (default 1234).

--sdk-version string

Version of the Adapnex SDK to use (default "latest"). Only relevant when <executable> names a CMake target, which is built before deployment.
Example: Deploy an application together with a config file and enable auto-restart.
adapnex app run line_1_plc conveyor_controller ./config.json --app conveyor

List applications

Displays the status of all managed applications on a device, including their running state, executable name, and active version tag.

adapnex app list <device>
Example: List all applications on the "line_1_plc" device
$ adapnex app list line_1_plc

╭──────────┬─────────┬─────────┬─────────────────────┬─────────────────────────╮
│   App    │ Status  │ Restart │     Executable      │         Version         │
├──────────┼─────────┼─────────┼─────────────────────┼─────────────────────────┤
│ main     │ stopped │ enabled │ example_app         │ main_20260126012221     │
│ conveyor │ running │ enabled │ conveyor_controller │ conveyor_20260126012300 │
╰──────────┴─────────┴─────────┴─────────────────────┴─────────────────────────╯

The Restart column shows whether the automatic restart policy is enabled, which is controlled by the --once flag of the app run command.

Stop application

Terminates a running application. If auto-restart is enabled, the application will be restarted automatically on the next device reboot.

adapnex app stop <device> [flags]
Flag Description

--app string

The name of the application to stop (default "main").
Example: Stop the "conveyor" application on the "line_1_plc" device
adapnex app stop line_1_plc --app conveyor

Start application

Starts an existing Adapnex application that was previously deployed to a device.

adapnex app start <device> [flags]
Argument Description

<device>

Target device ID or alias.
Flag Description

--app string

Name of the application to start (default "main").

--debug

Attaches a debugger when starting the application.

--detached

Starts the application without attaching to output.

--once

Disables restart of the application on crash or reboot.

--port int

Port to listen on for the debugger connection (default 1234).
Example: Start the "conveyor" application in detached mode on the "line_1_plc" device
adapnex app start line_1_plc --app conveyor --detached

Remove application

Stops the application (if running) and removes it from the controller.

adapnex app remove <device> [flags]
Flag Description

--app string

The name of the application to remove (default "main").
Example: Remove the "conveyor" application from the "line_1_plc" device
adapnex app remove line_1_plc --app conveyor

Attach to application

Connects your local terminal to the STDOUT and STDERR streams of a running application on the remote device.

adapnex app attach <device> [flags]
Flag Description

--app string

The application name (default "main").

--debug

Sets up a tunnel for remote debugging (see below).

--port int

Local port to listen on for the debugger connection (default 1234).
Example: Attach to the "conveyor" application on the "line_1_plc" device
adapnex app attach line_1_plc --app conveyor

Print application log

Prints the log of an application on a target device. By default, the entire log is printed. When -n or --lines is specified, only the requested number of trailing lines is displayed. The log can be retrieved whether the application is running, stopped, or terminated.

adapnex app log <device> [flags]
Argument Description

<device>

Target device ID or alias.
Flag Description

--app string

Name of the application to print the log of (default "main").

-n, --lines int

Print only the last n lines of the log.
Example: Print the entire log of the "conveyor" application
adapnex app log line_1_plc --app conveyor
Example: Print the last 50 lines of the default application log
adapnex app log line_1_plc -n 50

Remote Debugging

Adapnex simplifies remote debugging. You can attach gdb to a process running on the industrial controller as if it were running locally.

To debug a running application:

  1. Attach with Debug Mode:

    adapnex app attach <device> --debug

    This command establishes a secure tunnel and listens on localhost:1234, or on the port given by --port.

  2. Connect GDB: Configure your IDE or command-line GDB to connect to the remote target at localhost:1234.

Device Management

Manage the identity and user permissions of the hardware assets in your fleet.

Activate device

Claims an uncommissioned device on the local network and links it to your user account. This includes devices connected directly to your computer.

A device can only be activated once. To provide another user access to an already activated device, use adapnex device permission grant.

When run interactively without specifying a device, the local network is searched for devices that can be activated, and you choose one from the list. After activation, the command prompts you to assign an optional name to the device. Specifying <device> activates that specific device directly.

In non-interactive scripts or when output formatting flags (-o or --output) are used without specifying <device>, the command discovers and prints the list of activatable devices without prompting. You can then run the command again with the chosen device ID.

adapnex device activate [<device>]
Argument Description

[<device>]

Optional device ID of a controller found on the local network. When omitted, discovers available devices interactively.
Example: Discover and activate a device interactively
adapnex device activate
Example: Activate a specific device by its ID
adapnex device activate 00002474729

List devices

Displays a table of all devices associated with your account, including their unique IDs, aliases, hardware types (e.g., bnr_x20eds410 or wago_cc100), and permission summaries.

adapnex device list
Example: List all devices available in your account
$ adapnex device list

╭─────────────┬───────────────┬───────────────┬─────────────╮
│   Device    │     Name      │     Type      │ Permissions │
├─────────────┼───────────────┼───────────────┼─────────────┤
│ 00002474729 │ oven_control  │ wago_cc100    │ 1 user      │
│ 35A60168425 │ assembly_line │ bnr_x20eds410 │ 1 user      │
│ 35A60168429 │ test_bench    │ bnr_x20eds410 │ 3 users     │
╰─────────────┴───────────────┴───────────────┴─────────────╯

Rename device

Assigns a human-readable alias/name to a device ID. Aliases can be used interchangeably with Device IDs in all other commands.

adapnex device rename <device> <new-name>
Argument Description

<device>

The Device ID or current alias.

<new-name>

The new alias to assign.
Example: Rename the device with ID "35A60168425" to "line_1_plc"
adapnex device rename 35A60168425 line_1_plc

Copy files

Copies files between the local machine and Adapnex devices, or between two devices. Paths on a device are prefixed with the device name and a colon, such as my-device:/var/log/app.log. Quote wildcards in remote paths (for example 'my-device:/var/log/*.log'), otherwise the local shell expands them against local files.

adapnex device copy <source>... <destination> [flags]
Argument Description

<source>…​

One or more source paths, either local or remote (<device>:<path>).

<destination>

The target path, either local or remote (<device>:<path>).
Flag Description

-p, --preserve

Preserves modification times and file modes.

-r, --recursive

Copies directories recursively.
Example: Copy a remote log file to the local directory
adapnex device copy line_1_plc:/var/log/app.log ./logs/
Example: Copy a directory recursively to a device
adapnex device copy -r ./configs line_1_plc:/etc/my-app/

Open shell

Opens an interactive shell session or runs a command directly on an Adapnex device.

adapnex device shell <device> [<command>...] [flags]
Argument Description

<device>

Target device ID or alias.

<command>…​

(Optional) Command and arguments to execute on the remote device. If omitted, an interactive shell is launched.
Flag Description

-t, --tty

Forces allocation of a pseudo-terminal.

-T, --no-tty

Disables allocation of a pseudo-terminal.
Example: Open an interactive shell on the "line_1_plc" device
adapnex device shell line_1_plc
Example: Run a single command on the remote device
adapnex device shell line_1_plc -- uname -a

Manage device addresses

Configures explicit IPv4 addresses where an Adapnex device may be reached on the local network.

List addresses

Displays all configured reachability addresses for a device.

adapnex device address list <device>
Argument Description

<device>

Target device ID or alias.
Example: List all configured addresses for "line_1_plc"
$ adapnex device address list line_1_plc
╭────────────────┬───────────┬──────────────────┬──────────┬─────────────────────╮
│    Address     │ Added By  │      Email       │ Identity │      Added On       │
├────────────────┼───────────┼──────────────────┼──────────┼─────────────────────┤
│ 192.168.1.50   │ Fred Nerk │ [email protected] │ Google   │ 2026-01-03 08:21:45 │
│ 192.168.100.10 │ Fred Nerk │ [email protected] │ Google   │ 2026-01-05 14:12:08 │
╰────────────────┴───────────┴──────────────────┴──────────┴─────────────────────╯

Add address

Registers a new IPv4 address for reaching the device.

adapnex device address add <device> <address>
Argument Description

<device>

Target device ID or alias.

<address>

The IPv4 address to register (e.g. 192.168.1.50).
Example: Add an IPv4 address for "line_1_plc"
adapnex device address add line_1_plc 192.168.1.50

Remove address

Removes a previously configured IPv4 address from a device.

adapnex device address remove <device> <address>
Argument Description

<device>

Target device ID or alias.

<address>

The IPv4 address to remove.
Example: Remove an IPv4 address from "line_1_plc"
adapnex device address remove line_1_plc 192.168.1.50

Access Control

Manage multi-user collaboration for specific hardware. Adapnex allows granular access control, enabling you to grant specific engineers access to specific machines without sharing passwords or SSH keys.

List device permissions

Shows all users who have been granted access to a specific device.

adapnex device permission list <device>
Example: List all users with access to the "test_bench" device
$ adapnex device permission list test_bench

╭────────────┬──────────────────┬──────────┬─────────────────────╮
│    Name    │      Email       │ Identity │      Added On       │
├────────────┼──────────────────┼──────────┼─────────────────────┤
│ Fred Nerk  │ [email protected] │ Google   │ 2026-01-03 08:21:45 │
│ Jane Smith │ [email protected] │ Google   │ 2026-01-01 12:34:34 │
│ Tom Cobley │ [email protected]  │ GitHub   │ 2026-01-03 15:43:23 │
╰────────────┴──────────────────┴──────────┴─────────────────────╯

Grant device permission

Grants a user access to a device via their email address.

adapnex device permission grant <device> <email>
Example: Grant access to the "line_1_plc" device for "[email protected]"
adapnex device permission grant line_1_plc [email protected]

Revoke device permission

Revokes a user’s access to a device.

adapnex device permission revoke <device> <email>
Example: Revoke access to the "line_1_plc" device for "[email protected]"
adapnex device permission revoke line_1_plc [email protected]

Device Diagnostics & Service

Perform diagnostics and service operations on a device.

Check device version

Reports the version of the Adapnex Daemon running on a device.

adapnex diagnostic version <device> [flags]
Flag Description

--detailed

Also report the operating system and CPU architecture of the device.

Update device daemon

Downloads the latest Adapnex Daemon release and installs it. The device must be restarted for the new version to take effect.

adapnex diagnostic update <device>

Test connection speed

Measures round-trip latency and throughput on the connection to a device.

adapnex diagnostic speedtest <device>

CLI Maintenance

Show version

Prints the version of the CLI itself, along with the host platform.

adapnex version

Update the CLI

Updates the CLI to the latest release and refreshes the cached SDK and toolchain manifests, so that subsequent builds pick up new releases.

adapnex update [flags]
Flag Description

--force

Reinstall even if the latest version is already installed.

Output Formats

By default, the CLI prints results as human-readable tables. For scripting and CI/CD pipelines, the global --output flag switches any command that returns data to a machine-readable format.

Flag Description

-o, --output string

Output format: text, json, csv or tsv (default "text").
Example: List devices as JSON
$ adapnex device list --output json

[
  {
    "id": "00002474729",
    "alias": "oven_control",
    "type": "wago_cc100",
    "user_count": 1
  },
  {
    "id": "35A60168425",
    "alias": "assembly_line",
    "type": "bnr_x20eds410",
    "user_count": 1
  },
  {
    "id": "35A60168429",
    "alias": "test_bench",
    "type": "bnr_x20eds410",
    "user_count": 3
  }
]
Example: List devices as CSV
$ adapnex device list --output csv

id,alias,type,user_count
00002474729,oven_control,wago_cc100,1
35A60168425,assembly_line,bnr_x20eds410,1
35A60168429,test_bench,bnr_x20eds410,3
Example: Find every device shared with more than one user
adapnex device list -o json | jq -r '.[] | select(.user_count > 1) | .alias'

The flag has no effect on app run, app attach, app log, build, test and login.

Environment Variables

For CI/CD pipelines (e.g., GitHub Actions), you can configure the CLI using environment variables instead of interactive login.

Variable Description

ADAPNEX_AUTHN_TOKEN

A valid user authentication token. Used for headless authentication in CI/CD environments.

ADAPNEX_AUTHZ_URL

The URL of the authorization server. Defaults to the standard Adapnex Cloud endpoint.

ADAPNEX_PROXY_SERVER

The proxy server used for remote device connections. Defaults to the Adapnex Cloud proxy.

ADAPNEX_SDK_ROOT

Path to local Adapnex SDK installation. Used to override automatic SDK management.

ADAPNEX_TOOLCHAIN_ROOT

Path to local Adapnex toolchain installation. Used to override automatic toolchain management.

Up Next

Introduction to Adapnex →

Build a Hello World Project →

Working with Function Blocks →

SDK Reference →