MagicSuite.Cli 4.1.184

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

• .NET 9.0 SDK or later

As a .NET Global Tool (Recommended)

dotnet tool install -g MagicSuite.Cli

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 9
• System.CommandLine
• Spectre.Console
• MagicSuite.Api

Version: 1.0.0 (MVP)