Introduction

Get started with the Magistrala CLI (magistrala-cli) to manage workspaces, devices, gateways, device types, channels, and groups from your terminal.

The Magistrala CLI (magistrala-cli) is a thin command-line wrapper over Atom's GraphQL API — every resource command (workspaces, channels, groups, devices, gateways, devicetypes, users, authz) ultimately talks to Atom, not to a per-entity Magistrala microservice. Its source lives in the magistrala repository's cli/ package, built by cmd/cli/main.go.

Installation

Build from source

git clone https://github.com/absmach/magistrala.git
cd magistrala
make cli

make cli compiles cmd/cli/main.go (the CLI build target in the Makefile, alongside the regular service targets) and places the binary at ./build/cli. Install it system-wide if you want it on PATH:

sudo cp ./build/cli /usr/local/bin/magistrala-cli

Prebuilt binaries / Docker image

At the time of writing, releases on the Magistrala releases page do not consistently include a magistrala-cli binary, and the Makefile's Docker targets ($(DOCKERS)) are built only from $(SERVICES), which does not include cli — so there is no confirmed, currently-published magistrala-cli Docker image to pull. Building from source above is the verified path.

Usage

magistrala-cli --help

Available Commands:
  authz        Run Atom authorization checks
  channels     Manage Magistrala channels through Atom resources
  completion   Generate the autocompletion script for the specified shell
  devices      Devices management
  devicetypes  Device types management
  gateways     Device-gateway reachability
  groups       Manage Magistrala groups through Atom groups
  health       Health Check
  help         Help about any command
  login        Authenticate against Atom
  password     Manage the authenticated user's password
  users        Users management
  workspaces   Manage Magistrala workspaces through Atom tenants

Flags:
      --graphql-url string   Atom GraphQL endpoint
  -h, --help                  help for magistrala-cli
  -l, --limit uint            Limit query parameter
  -n, --name string           Name query parameter
  -o, --offset uint           Offset query parameter
  -r, --raw                   Enables raw output mode for easier parsing of output
      --token string          Atom bearer token

(Reconstructed from cli/root.go's command registration and persistent flags, not captured from a running binary. --graphql-url and --token have no shorthand. Verify with your own --help run before relying on exact flag text.)

Every resource command supports --help for its own usage, e.g. magistrala-cli devices --help.

Authentication

magistrala-cli login <identifier> <secret>

{ "token": "..." }

login also accepts --tenant-id / --tenant-alias for tenant-scoped credentials, and --kind (default password) for the credential kind. Pass the resulting token to subsequent commands with --token, or export it and reference it from your shell.

Health

magistrala-cli health <service>