iotctl CLI

iotctl is the command-line tool for managing the Iotistica Agent from the device itself. It covers provisioning, device configuration, diagnostics, backups, and everything else you would otherwise do through the admin UI — useful for scripting, SSH sessions, and automated provisioning pipelines.

Installation

iotctl is installed automatically by the install script. To install it separately:

curl -sfL https://get.iotistica.com/agent-cli | sudo sh

Verify the installation:

iotctl --version

Connection

iotctl talks to the agent's local REST API. By default it connects to http://localhost:48484. Override the address with environment variables if needed:

DEVICE_API_PORT=48484 iotctl status
# or
DEVICE_API_URL=http://localhost:48484 iotctl status

Running iotctl with Docker Compose

When the agent runs as a Docker container, add the agent-cli service to the same Compose file. It runs as a persistent sidecar — the container stays alive so you can docker exec into it at any time without restarting anything.

services:
  agent:
    image: iotistica/agent:latest
    container_name: iotistica-agent
    restart: unless-stopped
    ports:
      - "${AGENT_PORT:-48481}:48481"
    networks:
      - iotistica-net
    environment:
      - DEVICE_API_PORT=48481
      - STANDALONE=true
      - AGENT_SHELL_HMAC_KEY=${AGENT_SHELL_HMAC_KEY}
      # ... other agent env vars

  agent-cli:
    image: iotistica/agent-cli:latest
    container_name: iotistica-agent-cli
    restart: unless-stopped
    entrypoint: ["/bin/sh", "-c"]
    command: ["tail -f /dev/null"]
    tty: true
    networks:
      - iotistica-net
    environment:
      - DEVICE_API_PORT=48481
      - DEVICE_API_URL=http://agent:48481
      - CONFIG_DIR=/app/data
    volumes:
      - agent-cli-data:/app/data

volumes:
  agent-cli-data:

networks:
  iotistica-net:

tip

DEVICE_API_URL uses the service name (agent) as the hostname — Docker's internal DNS resolves it automatically within the shared network.

Running commands

# One-off command
docker exec iotistica-agent-cli iotctl status

# Interactive shell session
docker exec -it iotistica-agent-cli sh

# Then run commands as normal
iotctl diagnostics
iotctl devices list
iotctl db backup

Start the sidecar

docker compose up -d agent-cli

The CLI container logs are capped at 5 MB / 2 files (inherited from the agent stack defaults). The data volume at /app/data persists database backups across container restarts.

Command Reference

Command	Description
`iotctl status`	Device health and agent lifecycle
`iotctl diagnostics`	Full system diagnostic check
`iotctl logs`	Stream agent log output
`iotctl provision <key>`	Register device with the cloud
`iotctl deprovision`	Remove cloud registration
`iotctl factory-reset`	Wipe all data and reset
`iotctl config show`	Display configuration
`iotctl config set-api <url>`	Set cloud API endpoint
`iotctl devices list`	List configured device endpoints
`iotctl devices add-modbus`	Add a Modbus endpoint
`iotctl devices add-opcua`	Add an OPC-UA endpoint
`iotctl devices add-mqtt`	Add an MQTT source endpoint
`iotctl devices add-snmp`	Add an SNMP endpoint
`iotctl discover [protocol]`	Auto-discover devices on the network
`iotctl apps list`	List Docker applications
`iotctl services list`	List Docker services
`iotctl services logs <id>`	Tail service logs
`iotctl publish destinations list`	List publish destinations
`iotctl publish subscriptions list`	List subscriptions
`iotctl mqtt users`	List MQTT broker users
`iotctl db backup`	Create a database backup
`iotctl db restore`	Restore from backup
`iotctl db stats`	Database size and record counts
`iotctl buffer`	Offline buffer status
`iotctl memory`	Memory usage and leak detection
`iotctl agent update`	Update the agent to a new version
`iotctl agent restart`	Restart agent services
`iotctl agent pull`	Pull target state from cloud

Status & Diagnostics

`iotctl status`

Quick health check — shows agent version, provisioning state, MQTT connection, and service uptime.

iotctl status

`iotctl diagnostics`

Runs a full diagnostic sweep and prints a pass/fail for each system component: Device API, database, provisioning, internet connectivity, environment variables, lifecycle, cloud API, and MQTT broker.

iotctl diagnostics
# alias: iotctl diag

`iotctl logs`

Stream agent log output via journald (systemd installs only — must run from host, not inside a container).

iotctl logs                    # last 50 lines
iotctl logs -f                 # follow (alias: --follow)
iotctl logs -n 200             # last 200 lines

Provisioning

`iotctl provision <key>`

iotctl provision abc123xyz --api https://api.iotistica.com
iotctl provision abc123xyz --api https://api.iotistica.com --name factory-gateway-01

Flag	Required	Description
`--api <url>`	Yes	Cloud API endpoint
`--name <name>`	No	Device display name (auto-generated if omitted)
`--type <type>`	No	Device type label

`iotctl provision status`

Show current provisioning state.

iotctl provision status

`iotctl deprovision`

Remove cloud registration. Pass --yes to skip the confirmation prompt.

iotctl deprovision --yes

`iotctl factory-reset`

Deletes all data except the device UUID. Cannot be undone.

iotctl factory-reset --yes

Configuration

`iotctl config show`

Display the full agent configuration.

iotctl config show

`iotctl config set-api` / `get-api`

iotctl config set-api https://api.iotistica.com
iotctl config get-api

`iotctl config set` / `get`

Read or write arbitrary configuration keys. Values are parsed as JSON if valid, otherwise stored as strings.

iotctl config set maxConnections 100
iotctl config get maxConnections

Device Endpoints

Endpoints are the industrial devices the agent collects data from. Commands mirror the Endpoints section of the admin UI.

`iotctl devices list`

iotctl devices list                      # all protocols
iotctl devices list --protocol modbus    # filter by protocol

`iotctl devices show <name>`

iotctl devices show factory-plc

Enable / disable / remove

iotctl devices enable <uuid>
iotctl devices enable all            # enable every device at once

iotctl devices disable <uuid>
iotctl devices remove <uuid>
iotctl devices clean             # dry-run: shows what would be removed
iotctl devices clean --force     # actually remove all device configs

`iotctl devices add-modbus`

iotctl devices add-modbus \
  --name factory-plc \
  --host 192.168.1.100 \
  --port 502 \
  --slave 1 \
  --interval 5000

Flag	Default	Description
`--name`	—	Device name (required)
`--host`	—	IP address or hostname (required)
`--port`	`502`	TCP port
`--slave`	`1`	Modbus slave ID
`--interval`	`5000`	Poll interval in ms
`--disabled`	—	Create in disabled state

`iotctl devices add-opcua`

iotctl devices add-opcua \
  --name process-server \
  --endpoint opc.tcp://192.168.1.50:4840 \
  --interval 5000

Flag	Default	Description
`--name`	—	Device name (required)
`--endpoint`	—	OPC-UA endpoint URL `opc.tcp://…` (required)
`--interval`	`5000`	Poll interval in ms
`--disabled`	—	Create in disabled state

`iotctl devices add-mqtt`

iotctl devices add-mqtt \
  --name sensor-broker \
  --broker mqtt://192.168.1.10:1883 \
  --topics sensors/#,status/+ \
  --username admin \
  --password secret

Flag	Default	Description
`--name`	—	Device name (required)
`--broker`	—	Broker URL `mqtt://…` (required)
`--topics`	—	Comma-separated topic list
`--username`	—	MQTT username
`--password`	—	MQTT password
`--interval`	`5000`	Poll interval in ms
`--disabled`	—	Create in disabled state

`iotctl devices add-snmp`

iotctl devices add-snmp \
  --name network-switch \
  --host 192.168.1.1 \
  --community public

Flag	Default	Description
`--name`	—	Device name (required)
`--host`	—	IP address or hostname (required)
`--port`	`161`	UDP port
`--community`	`public`	SNMP community string
`--interval`	`30000`	Poll interval in ms
`--disabled`	—	Create in disabled state

Discovery

Scan the local network for compatible devices.

iotctl discover              # all supported protocols
iotctl discover modbus       # Modbus only (can take 30–60 s for slave ID scan)
iotctl discover opcua
iotctl discover mqtt

iotctl discover modbus --validate   # connect and validate found devices

Apps & Services

The agent can orchestrate Docker applications (app stacks) composed of individual services. These commands manage them from the command line.

Applications

iotctl apps list
iotctl apps start  <appId>
iotctl apps stop   <appId>
iotctl apps restart <appId>
iotctl apps info   <appId>
iotctl apps purge  <appId> --yes    # delete all volumes — cannot be undone

Services

iotctl services list                   # all services
iotctl services list <appId>           # services for one app

iotctl services start   <serviceId>
iotctl services stop    <serviceId>
iotctl services restart <serviceId>

iotctl services logs <serviceId>              # last 100 lines
iotctl services logs <serviceId> -f          # follow (alias: --follow)

iotctl services info <serviceId>

Publish Destinations & Subscriptions

Manage how collected data is routed to external systems (MQTT brokers, InfluxDB, cloud IoT platforms).

Destinations

iotctl publish destinations list
iotctl publish destinations list --include-disabled

# Add an MQTT publish destination
iotctl publish add mqtt \
  --name cloud-broker \
  --broker mqtt://cloud.example.com:1883 \
  --username device-01 \
  --password secret

Subscriptions

iotctl publish subscriptions list
iotctl publish subscriptions list --publish-destination-id 1

# Add a subscription
iotctl publish subscriptions add \
  --publish-destination-id 1 \
  --destination-topic telemetry/factory \
  --protocols modbus,opcua \
  --payload-format tags

Flag	Default	Description
`--publish-destination-id`	—	Destination ID — use this or `--destination-name` (one required)
`--destination-name`	—	Destination name — alternative to `--publish-destination-id`
`--destination-topic`	—	MQTT topic or InfluxDB measurement (required)
`--protocols`	all	Comma-separated protocol filter
`--payload-format`	`custom`	`custom`, `tags`, or `ecp`
`--compression`	none	`json`, `msgpack`, `json+deflate`, `msgpack+deflate`
`--include-devices`	—	Only publish from these device names
`--exclude-devices`	—	Exclude these device names
`--disabled`	—	Create in disabled state

MQTT Broker Users

List users registered in the local Mosquitto broker (only relevant when the agent manages a local Mosquitto instance).

iotctl mqtt users

Database

The agent stores all state in a single SQLite file. These commands manage backups and health checks.

iotctl db stats              # database size and table record counts (alias: db info)
iotctl db backups list       # list all backups with timestamps and sizes

iotctl db backup             # create a timestamped backup
iotctl db backup my-snapshot # create a named backup

iotctl db verify             # verify integrity of the latest backup
iotctl db verify my-snapshot

iotctl db restore --yes                  # restore latest backup
iotctl db restore my-snapshot --yes      # restore named backup
iotctl db restore --yes --force-live     # restore while agent is running (dangerous)

iotctl db prune              # keep last 24 backups, delete older ones
iotctl db prune --keep 10    # keep last 10

warning

db restore stops the agent, replaces the database, and restarts. All in-memory state is lost. Use --force-live only when you understand the risk.

Buffer & Memory

`iotctl buffer`

Shows the size of the offline queues — messages that are waiting to be delivered when a destination or cloud connection is restored.

iotctl buffer

`iotctl memory`

Detailed memory breakdown: heap used/total, RSS, external allocations, survivor object count, and whether the leak detector has triggered any warnings.

iotctl memory

Agent Control

Restart

Reinitializes all agent services (the API and MQTT connection stay up during the restart).

iotctl agent restart
# alias: iotctl restart

Pull state from cloud

Immediately fetches the latest target state from the cloud and applies it, instead of waiting for the next scheduled sync interval.

iotctl agent pull

Update

Download and install a new agent version. The service restarts automatically when the update completes.

iotctl agent update              # update to latest
iotctl agent update 1.0.600      # update to a specific version
iotctl agent update --force      # reinstall even if already on that version

# alias: iotctl update [<version>] [--force]

Installation​

Connection​

Running iotctl with Docker Compose​

Running commands​

Start the sidecar​

Command Reference​

Status & Diagnostics​

iotctl status​

iotctl diagnostics​

iotctl logs​

Provisioning​

iotctl provision <key>​

iotctl provision status​

iotctl deprovision​

iotctl factory-reset​

Configuration​

iotctl config show​

iotctl config set-api / get-api​

iotctl config set / get​

Device Endpoints​

iotctl devices list​

iotctl devices show <name>​

Enable / disable / remove​

iotctl devices add-modbus​

iotctl devices add-opcua​

iotctl devices add-mqtt​

iotctl devices add-snmp​

Discovery​

Apps & Services​

Applications​

Services​

Publish Destinations & Subscriptions​

Destinations​

Subscriptions​

MQTT Broker Users​

Database​

Buffer & Memory​

iotctl buffer​

iotctl memory​

Agent Control​

Restart​

Pull state from cloud​

Update​