MagicSuite.Cli 4.2.872

MagicSuite CLI

A powerful command-line interface for Magic Suite operations, providing full CRUD capabilities, tenant management, and beautiful console output.

Features

• ? Full CRUD Operations - Create, read, update, and delete entities
• ?? File System Operations - Upload, download, and manage files
• ?? Tenant Management - Switch between tenants with intelligent resolution
• ?? Multiple Profiles - Manage different environments (alpha, staging, production)
• ??? Flexible Authentication - API tokens with environment variable support
• ?? Beautiful Output - Table and JSON formats with color-coded displays
• ?? Safety Features - Confirmation prompts and restricted operations
• ?? Future: Real-time monitoring via SignalR

Installation

Prerequisites

?? Important: This tool requires .NET 10 SDK or later.

The tool will not install on systems with only .NET 9 or earlier.

Check your installed SDKs:

dotnet --list-sdks

Download .NET 10 SDK: https://dotnet.microsoft.com/download/dotnet/10.0

As a .NET Global Tool (Recommended)

dotnet tool install -g MagicSuite.Cli

If you see an error like Package MagicSuite.Cli is not compatible with net9.0, you need to install the .NET 10 SDK first.

Via Winget (Windows Package Manager)

winget install PanoramicData.MagicSuite.Cli

From Source

cd MagicSuite.Cli
dotnet build
dotnet run -- --help

Verify Installation

magicsuite --version
magicsuite --help

Quick Start

First-Time Setup

Run the interactive configuration wizard:

magicsuite config init

This will guide you through:

1. Creating your first profile
2. Setting up API URL
3. Configuring authentication credentials

Manual Setup

# Create a profile
magicsuite config profiles add alpha2

# Configure API URL
magicsuite config set api-url https://api.alpha2.magicsuite.com

# Set up authentication
magicsuite auth token --name your-token-name --key your-api-token-key

# Test connection
magicsuite auth status

Commands Reference

Configuration Commands

Profile Management

# List all profiles
magicsuite config profiles list

# Add new profile
magicsuite config profiles add production

# Set active profile
magicsuite config profiles set-active production

# Remove profile
magicsuite config profiles remove old-profile

Settings Management

# View all configuration
magicsuite config list

# Get specific setting
magicsuite config get api-url

# Set configuration value
magicsuite config set default-format json
magicsuite config set api-url https://api.magicsuite.com

Authentication Commands

# Set API token credentials
magicsuite auth token --name token-name --key token-key

# Check authentication status (includes connection test)
magicsuite auth status

# Clear stored credentials
magicsuite auth logout

API Commands - Read Operations

List Entities

# Get all tenants
magicsuite api get tenants

# Get with filtering
magicsuite api get tenants --filter "Acme"
magicsuite api get connections --filter "LogicMonitor"

# Limit results
magicsuite api get tenants --top 5

# Expand navigation properties
magicsuite api get connections --expand tenant

# JSON output
magicsuite api get tenants --format json

# Combined options
magicsuite api get connections --filter "Logic" --top 10 --format json

Supported Entity Types:

• tenants - Tenant/customer information
• connections - System connections (LogicMonitor, Meraki, etc.)
• reportschedules - Scheduled report configurations
• people - User accounts

Get Single Entity

# Get by ID (shows detailed properties)
magicsuite api get-by-id tenant 123
magicsuite api get-by-id connection 456
magicsuite api get-by-id reportschedule 789

# With expansion
magicsuite api get-by-id connection 456 --expand tenant

# JSON format
magicsuite api get-by-id tenant 123 --format json

API Commands - Create Operations

# Create with inline JSON
magicsuite api create connection --json '{"Name":"Production LM","ConnectionType":"LogicMonitor","Url":"https://company.logicmonitor.com"}'

# Create from JSON file
magicsuite api create connection --json-file new-connection.json

# Create report schedule
magicsuite api create reportschedule --json '{"Name":"Daily Report","CronSchedule":"0 0 * * *","IsEnabled":true}'

Example JSON file (new-connection.json):

{
  "Name": "Production LogicMonitor",
  "ConnectionType": "LogicMonitor",
  "Url": "https://company.logicmonitor.com/santaba",
  "UserName": "api@company.com",
  "Password": "your-access-key",
  "Description": "Main monitoring system"
}

API Commands - Update Operations

# Partial update (PATCH) - recommended
magicsuite api patch connection 456 --json '{"Name":"Updated Name"}'
magicsuite api patch connection 456 --json '{"Description":"New description","Url":"https://new-url.com"}'

# Update from file
magicsuite api patch connection 456 --json-file updates.json

# Update with JSON output
magicsuite api patch connection 456 --json '{"IsEnabled":false}' --format json

API Commands - Delete Operations

# Delete with confirmation prompt
magicsuite api delete connection 456

# Delete without confirmation (for automation)
magicsuite api delete connection 456 --confirm

# Example: Delete report schedule
magicsuite api delete reportschedule 789

Safety Notes:

• Tenants and people cannot be deleted via CLI (use Admin UI)
• Confirmation required unless --confirm flag is used
• Displays entity name before deletion

Tenant Commands

# Switch to different tenant (by code)
magicsuite tenant select ACME01

# Switch by ID
magicsuite tenant select 123

# Switch by GUID
magicsuite tenant select 550e8400-e29b-41d4-a716-446655440000

# Show current tenant
magicsuite tenant current

# Current tenant as JSON
magicsuite tenant current --format json

Requirements:

• Only Super Admin or Uber Admin can switch tenants
• Tenant selection is cached for session performance

File System Commands

Manage files and folders in the Magic Suite file system.

List Files and Folders

# List root directory
magicsuite file list

# List specific folder
magicsuite file list /Library

# List with JSON output
magicsuite file list /Reports --format json

Upload Files

# Upload a file
magicsuite file upload report.pdf /Reports/monthly.pdf

# Force overwrite existing file
magicsuite file upload data.csv /Library/data.csv --force

# Upload to subfolder
magicsuite file upload image.png /Library/images/logo.png

Download Files

# Download a file
magicsuite file download /Reports/monthly.pdf ./local-report.pdf

# Download to current directory
magicsuite file download /Library/data.csv ./data.csv

# Download to specific directory
magicsuite file download /Reports/analysis.xlsx ./downloads/analysis.xlsx

Create Folders

# Create a new folder
magicsuite file create-folder /Reports/2024

# Create nested folder
magicsuite file create-folder /Library/Projects/NewProject

Rename/Move Files

# Rename a file
magicsuite file rename /old-name.pdf /new-name.pdf

# Move a file to different folder
magicsuite file rename /Temp/file.pdf /Archive/file.pdf

# Rename a folder
magicsuite file rename /OldFolder /NewFolder

Copy Files

# Copy a file
magicsuite file copy /source.pdf /backup.pdf

# Copy to different folder
magicsuite file copy /Reports/monthly.pdf /Archive/Reports/monthly-backup.pdf

# Copy a folder (recursive)
magicsuite file copy /Reports /Archive/Reports-Backup

Delete Files and Folders

# Delete with confirmation prompt
magicsuite file delete /Temp/old-file.pdf

# Delete without confirmation (for scripts)
magicsuite file delete /OldFolder --confirm

# Delete specific file
magicsuite file delete /Reports/outdated-report.pdf

Search for Files

# Search everywhere
magicsuite file search 'budget'

# Search in specific path
magicsuite file search 'report' --path /Reports

# Search with JSON output
magicsuite file search '*.pdf' --format json

# Search for files by pattern
magicsuite file search 'Q1-2024'

File Operations Features:

• ? Human-readable file sizes (B, KB, MB, GB, TB)
• ? Type indicators (? folders, ? files)
• ? Formatted timestamps
• ? Safety confirmations for destructive operations
• ? Recursive folder operations
• ? Path validation

Global Options

All commands support these global options:

--profile <name>       Use specific profile (e.g., alpha2, production)
--format <json|table>  Output format (default: table)

Examples:

# Use production profile
magicsuite api get tenants --profile production

# Force JSON output
magicsuite config list --format json

# Combine options
magicsuite api get connections --profile alpha2 --format json

Output Formats

Table Format (Default)

Beautiful, color-coded tables using Spectre.Console:

• Property/value pairs for single entities
• Columnar tables for lists
• Color highlighting for important fields
• Emoji indicators (?, ?)

JSON Format

Pretty-printed JSON with camelCase naming:

magicsuite api get-by-id tenant 123 --format json

Configuration File

Configuration is stored at:

• Windows: %APPDATA%\MagicSuite\cli-config.json
• Linux/Mac: ~/.config/MagicSuite/cli-config.json

Example configuration:

{
  "activeProfile": "alpha2",
  "profiles": {
    "alpha2": {
      "apiUrl": "https://api.alpha2.magicsuite.com",
      "tokenName": "dev-token",
      "tokenKey": "your-key-here"
    },
    "production": {
      "apiUrl": "https://api.magicsuite.com",
      "tokenName": "prod-token",
      "tokenKey": "your-prod-key"
    }
  },
  "defaultOutputFormat": "table"
}

Environment Variables

For CI/CD and automation, use environment variables:

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

# Then use CLI without explicit credentials
magicsuite api get tenants

Priority: Environment variables > Profile configuration > Command-line options

Command Cheat Sheet

Common Workflows

Setup new environment:

magicsuite config profiles add staging
magicsuite config set api-url https://api.staging.magicsuite.com
magicsuite auth token --name staging-token --key abc123
magicsuite auth status

Query and filter data:

magicsuite api get connections --filter "Logic" --top 5
magicsuite api get-by-id connection 456 --expand tenant

Create and configure:

magicsuite api create connection --json-file connection.json
magicsuite api patch connection 456 --json '{"IsEnabled":true}'

Tenant operations:

magicsuite tenant select ACME01
magicsuite api get connections
magicsuite tenant current

File management:

magicsuite file list /Library
magicsuite file upload report.pdf /Reports/monthly.pdf
magicsuite file download /Reports/monthly.pdf ./report.pdf
magicsuite file search 'budget' --path /Reports
magicsuite file delete /Temp/old-files --confirm

Error Handling

The CLI provides helpful error messages:

# Missing credentials
Error: Missing API credentials.
Run 'magicsuite config init' or 'magicsuite auth token' to configure credentials.

# Entity not found
Error: Connection with ID 999 not found.

# Permission denied
Error: Tenant switching requires Super Admin or Uber Admin privileges.
Current user: john@example.com (john)

Development Status

? Completed (Phases 1-5)

• Core infrastructure
• Configuration management
• Authentication system
• Full CRUD API operations
• Tenant management
• Beautiful output formatting

?? Planned (Phases 6-9)

• Phase 6: Testing & Documentation (In Progress)
• Phase 7: Packaging & Distribution
• Phase 8: Advanced Features
• Phase 9: Real-time monitoring (SignalR)

See MS-22117.md for full implementation plan.

Architecture

• Commands: Command implementations using System.CommandLine
• Services: Core services (Configuration, Authentication, OutputFormatter)
• Models: Configuration and data models
• API Client: Uses MagicSuite.Api NuGet package

Code Style

• Allman brace style
• Tabs for indentation
• Primary constructors (C# 12)
• No this. qualifier
• Follows .editorconfig rules

Contributing

This CLI is part of the Magic Suite platform by Panoramic Data Limited.

For bugs or feature requests, create a Jira ticket with the "Magic Suite" project.

License

Copyright � 2025 Panoramic Data Limited

Built with:

• .NET 10
• System.CommandLine
• Spectre.Console
• MagicSuite.Api

Version: See version.json (managed by Nerdbank.GitVersioning)