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.

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!

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

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

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

Adds a device to your account using a one-time activation code. Once activated, the device can be renamed with adapnex device rename.

adapnex device activate <activation-code>

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

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, 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 →