Mosquitto: Automate with the CLI

Start Mosquitto, retrieve its credentials, and change its configuration programmatically with the Stackhero CLI

👋 Welcome to the Stackhero documentation!

Stackhero gives you a fully managed Mosquitto MQTT cloud environment designed for reliability and flexibility:

Unlimited message throughput and data transfers, so your workflows never hit artificial limits.

Unlimited device authentication through your own external API, making onboarding and access management seamless.

Advanced ACLs for fine-grained control over topics, users, and actions.

A custom domain name with built-in HTTPS for secure, branded endpoints (for example: https://mqtt.your-company.com).

Zero-hassle updates: apply improvements or security patches with a single click.

Consistent performance and strong security, with every instance running on a private, dedicated infrastructure.

Accelerate your IoT projects and reduce operational overhead. You can have a secure, production-ready Mosquitto MQTT cloud hosting instance up and running in just a few minutes.

This guide shows how to create a Mosquitto service, read its credentials, and update its configuration entirely from the command line, with no clicks in the dashboard. It is ideal for scripts, CI pipelines, and AI agents.

We will be using the Stackhero CLI for all tasks. If you have not already, you can install it with:

curl -fsSL https://www.stackhero.io/install.sh | sh

1. Authenticate

The easiest way to get started is by logging in through your browser. When you run the login command, the CLI opens a web page where you can approve access. No passwords or 2FA codes are entered into the CLI itself.

stackhero login

After logging in, your credentials are stored locally and will be used automatically by future CLI commands.

For fully automated environments like scripts or CI pipelines, you might prefer a non-interactive access token. You can create one from your dashboard (Account > Access tokens), then export it as an environment variable. The CLI, and any script you run, will pick it up automatically.

export STACKHERO_TOKEN="usr-xxxxxx:your-token"

2. Find the Mosquitto service store

Next, you will want to list the Mosquitto service stores available to your account. The CLI accepts the store name (mosquitto) directly, so there is no need to look up or copy any IDs.

# List Mosquitto service stores (add --organization if you manage more than one)
stackhero services-store-list --name="mosquitto"

You can refer to the store name mosquitto in subsequent commands, or choose a specific svs-xxxxxx ID from the list if you prefer.

3. Pick an instance size and a region

# List instance sizes for your service store (use the NAME column for --instance)
stackhero instances-store-list --service-store=mosquitto

# List available regions (names like "europe")
stackhero regions-list

4. Create the service

Here is a sample script that creates a stack, adds your Mosquitto service to it, waits for it to start, retrieves its configuration (including generated credentials), and then applies a new configuration.

#!/bin/bash
set -e

export STACKHERO_TOKEN="usr-xxxxxx:your-token"

serviceStore="mosquitto"   # The Mosquitto service store name (see step 2)
instance="..."                # An instance size from step 3
region="europe"               # A region name from step 3

# Create a stack for your service (uses your default organization; add --organization if needed)
stackId=$(stackhero --format=script stack-create \
  --name="My Mosquitto stack")
echo "Stack created: ${stackId}"

# Add Mosquitto to the stack (names are resolved automatically)
serviceId=$(stackhero --format=script service-add \
  --stack="My Mosquitto stack" \
  --service-store="${serviceStore}" \
  --instance="${instance}" \
  --region="${region}")
echo "Service added: mosquitto"

# Wait for the service to be fully running (this may take a couple of minutes)
stackhero service-wait-for --service="mosquitto"

# Retrieve the service configuration, including generated credentials
stackhero service-configuration-get --service="mosquitto" --format=json

5. Retrieve credentials

The service-configuration-get command returns the complete configuration for your service, including auto-generated passwords and connection details. The output is in JSON format, making it easy to use in scripts and automation.

stackhero service-configuration-get --service=svc-xxxxxx --format=json

6. Change the configuration

You can review an example configuration schema and then apply your own settings. When you update the configuration, the service may restart to apply the changes.

# View the configuration schema and an example for your service
stackhero service-configuration-example --service=svc-xxxxxx

# Apply a custom configuration (the service restarts if needed)
stackhero service-configuration-set \
  --service=svc-xxxxxx \
  --configuration='{ "...": "..." }'

# Wait for the new configuration to be applied
stackhero service-wait-for --service=svc-xxxxxx

That is it. You have now seen the full lifecycle: start a service, retrieve its credentials, and reconfigure it, all in a scriptable, automated way. To dive deeper, check out the full CLI documentation, which also covers the non-interactive STACKHERO_TOKEN authentication demonstrated here.