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.
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  │     Executable      │         Version         │
├────────────┼─────────┼─────────────────────┼─────────────────────────┤
│ main       │ stopped │ example_app         │ main_20260126012221     │
│ conveyor   │ running │ conveyor_controller │ conveyor_20260126012300 │
╰────────────┴─────────┴─────────────────────┴─────────────────────────╯

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).
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.

  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.

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-oauth2 │ 2026-01-03 08:21:45 │
│ Jane Smith  │ [email protected] │ google-oauth2 │ 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]

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 →