Magic Suite CLI

magicsuite is the command-line interface to Magic Suite. It reads and writes Magic Suite data through the Magic Suite API, manages files, switches tenants and talks to Merlin, from a terminal, a script or an AI assistant.

Installation

The CLI is a .NET global tool and needs the .NET 10 SDK or later. Check with dotnet --list-sdks, and download the SDK from https://dotnet.microsoft.com/download/dotnet/10.0 if you need it.

# Install
dotnet tool install -g MagicSuite.Cli

# Upgrade
dotnet tool update -g MagicSuite.Cli

# Uninstall
dotnet tool uninstall -g MagicSuite.Cli

On Windows you can use winget instead:

winget install PanoramicData.MagicSuite.Cli

Check that it is installed:

magicsuite --version
magicsuite --help

If installation fails with Package MagicSuite.Cli is not compatible with net9.0, install the .NET 10 SDK first.

Signing in

The CLI signs in with an API token, not your password. Create one in Magic Suite on the My API Tokens page, /myapitokens in any Magic Suite app (for example https://www.magicsuite.net/myapitokens). You get a token name and a token key; the key is shown once, so copy it then.

A profile holds one environment's API URL and token. The production API URL is https://api.magicsuite.net.

# Create a profile with its API URL and token in one step
magicsuite config profiles add production --api-url https://api.magicsuite.net --token-name my-token-name --token-key my-token-key

# Make it the profile commands use by default
magicsuite config profiles set-active production

# Check the credentials work (this calls the API)
magicsuite auth status

Or let the wizard ask for each value:

magicsuite config init

You can also set or replace the token on an existing profile:

magicsuite auth token --name my-token-name --key my-token-key --profile production

Choosing the environment every time

--profile works on every command, before or after the subcommand. Name the profile explicitly in scripts and when handing the CLI to an AI assistant, so a command never runs against whichever profile happens to be active:

magicsuite api get reportschedules --profile production

Credentials from the environment

For CI/CD, credentials can come from environment variables instead of a profile:

export MAGICSUITE_API_URL="https://api.magicsuite.net"
export MAGICSUITE_TOKEN_NAME="automation-token"
export MAGICSUITE_TOKEN_KEY="your-token-key"

magicsuite api get tenants

Precedence is: options on the command line (--api-url, --token-name, --token-key), then environment variables, then the profile.

Commands

Every command has built-in help, which is always the most up-to-date reference:

magicsuite --help
magicsuite api --help
magicsuite api get --help

The command groups are config, auth, api, tenant, file, watch, feedback and merlin.

config: profiles and settings

# List profiles, and see which one is active
magicsuite config profiles list

# Add a profile (or overwrite one)
magicsuite config profiles add test --api-url https://api.test.magicsuite.net

# Switch the active profile
magicsuite config profiles set-active test

# Remove a profile
magicsuite config profiles remove test

# Show, read and change settings
magicsuite config list
magicsuite config get api-url
magicsuite config set default-format json
magicsuite config set default-tenant ACME --profile production

Settings are api-url, default-tenant, default-format (table or json) and verbose-logging.

auth: credentials

# Store a token on the active profile
magicsuite auth token --name my-token-name --key my-token-key

# Show who you are signed in as, and test the connection
magicsuite auth status

# Remove the stored token from a profile
magicsuite auth logout --profile test

api: read and change data

The api commands work on any Magic Suite entity type: magicsuite api --help lists them all. Entity type names are singular or plural (tenant or tenants).

# List entities (100 by default)
magicsuite api get reportschedules

# Choose the fields, the order and the page
magicsuite api get reportschedules --select Id,Name,IsEnabled --orderby "-Id" --take 20 --skip 20

# Name contains "Logic"
magicsuite api get connections --filter Logic

# JSON output, for scripts and AI assistants
magicsuite api get connections --select Id,Name --format json

# Write the output to a file
magicsuite api get reportschedules --format json --output schedules.json

# One entity by ID, with a related entity expanded
magicsuite api get-by-id reportschedule 123 --expand Tenant

--filter matches on name. For report macro results, --filter ReportJobId:944 lists the results of one report job.

Create and change entities with --set Property=Value, repeated once per property. There is no JSON body option: every value is a --set.

# Create
magicsuite api create reportschedule --set Name="Daily Report" --set IsEnabled=true

# Change some properties (PATCH, so everything else is left alone)
magicsuite api patch reportschedule 123 --set Name="Weekly Report" --set IsEnabled=false

# Delete, with a confirmation prompt
magicsuite api delete reportschedule 123

# Delete without the prompt, for scripts
magicsuite api delete reportschedule 123 --confirm

Tenants and people cannot be deleted from the CLI; use Admin in Magic Suite.

A whole configuration graph (for example an AlertMagic integration and everything under it) can be exported to a JSON document and imported again, which is how configuration is kept as code:

magicsuite api export eventmanager 42 --output integration.jsonc
magicsuite api import eventmanager 42 --file integration.jsonc

tenant: which tenant you are working in

# Show the current tenant
magicsuite tenant current

# Switch tenant by code, ID or GUID (Super Admin only)
magicsuite tenant select ACME

# List every tenant (Super Admin only)
magicsuite tenant list --format json

Super Admins can also scope a single api get with --tenant ACME, or see every tenant with --include-all-tenants.

file: the Magic Suite file store

# List a folder (the root if no path is given)
magicsuite file list /Library

# Upload, replacing any existing file
magicsuite file upload report.rmscript /Library/Reports/report.rmscript --force

# Download
magicsuite file download /Library/Reports/report.rmscript ./report.rmscript

# Search by name, optionally under one folder
magicsuite file search budget --path /Library

# Create, rename or move, and copy
magicsuite file create-folder /Library/Archive
magicsuite file rename /Library/old.rmscript /Library/Archive/old.rmscript
magicsuite file copy /Library/Reports /Library/Archive/Reports

# Delete, with a prompt unless --confirm is given
magicsuite file delete /Library/Archive/old.rmscript --confirm

watch: live events

Watch what Magic Suite is doing as it happens, for example report jobs being updated as they run:

magicsuite watch --subject ReportJob --type Update --timeout-seconds 300

feedback: tell us something

magicsuite feedback --summary "Export is slow" --description "Exporting 500 schedules took ten minutes" --rating 3

merlin: talk to the Magic Suite AI assistant

# An interactive conversation
magicsuite merlin chat --profile production

# One question, answered and then exit
magicsuite merlin chat --prompt "How many report schedules do I have?"

# Several turns in one conversation
magicsuite merlin chat --prompt "What is ReportMagic?" --prompt "Which macros draw graphs?"

# Prompts from a file (one per line; blank lines and # comments ignored), transcript saved
magicsuite merlin chat --script questions.txt --transcript conversation.md

While chatting, /new starts a fresh session, /history shows what will be sent, /save <file> saves the transcript, /raw shows the raw requests and responses, and /exit leaves.

The CLI uses the same Merlin endpoint as the chat panel in the browser, with one difference: the browser also sends the page you are looking at, and the CLI has no page. Questions such as "what am I looking at?" therefore behave differently here.

Options that work on every command

Option	Purpose
`--profile <name>`	The profile (environment) to use
`--format <format>`	Output format: `table` (the default) or `json`
`--output <file>`	Write the output to a file instead of the console
`--quiet`	Suppress status messages, leaving only the data
`--verbose`	Show detailed diagnostic output
`--tenant <tenant>`	Tenant code or ID to work in, overriding the profile's default tenant
`--api-url`, `--token-name`, `--token-key`	Credentials for this command only, overriding the profile

Using the CLI from an AI assistant

The CLI is a good way to let an AI assistant work with Magic Suite for you. Tell it to:

always pass --profile <name>, so it cannot run against the wrong environment;
use --format json --quiet, so it reads data rather than console decoration;
use --select to ask only for the fields it needs;
run magicsuite <command> --help when unsure, rather than guessing options.

The API token decides what the assistant can see and change: give it a token for an account with only the access it needs.

Configuration file

Profiles are stored in cli-config.json in the user's application data folder:

Windows: %APPDATA%\Panoramic Data\MagicSuite\cli-config.json
Linux and macOS: ~/.config/Panoramic Data/MagicSuite/cli-config.json

The file holds your token keys, so treat it like a password.

Getting help

magicsuite --help, and --help on any command
Documentation: https://docs.magicsuite.net/AdvancedTopics/Cli
Report a problem: magicsuite feedback, or contact Panoramic Data support

NuGet package: MagicSuite.Cli

Magic Suite CLI

Installation

Signing in

Choosing the environment every time

Credentials from the environment

Commands

config: profiles and settings

auth: credentials

api: read and change data

tenant: which tenant you are working in

file: the Magic Suite file store

watch: live events

feedback: tell us something

merlin: talk to the Magic Suite AI assistant

Options that work on every command

Using the CLI from an AI assistant

Configuration file

Getting help

Search

Reconnection

Reconnection

Reconnection