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, 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
  workspaces   Manage Magistrala workspaces through Atom tenants

Flags:
  -d, --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 — the checked-out magistrala working copy does not currently build cleanly (pkg/sdk/bootstrap.go references undefined enableEndpoint/disableEndpoint), unrelated to the CLI package itself. Verify with your own --help run before publishing 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>