Magentrix CLI - Command Reference

Overview

This document provides complete technical reference for all Magentrix CLI commands, their parameters, usage patterns, and examples.

Command Syntax Conventions

magentrix <command> [options] [arguments]

Notation Used:

• <required> - Required parameter
• [optional] - Optional parameter
• | - Choice between options
• ... - Can be repeated

Global Options

These options work with any command:

Examples:

magentrix --help
magentrix pull --help
magentrix --version

Command Overview

Core Commands (Alphabetical)

Detailed Command Reference

autopublish

Purpose: Watch local files for changes and automatically upload them to the Magentrix server when saved.

Syntax:

magentrix autopublish

Parameters: None

Behavior:

1. Starts file watcher on the src/ directory
2. Monitors for file changes (create, modify, delete)
3. Automatically uploads changed files to server
4. Compiles code on server
5. Displays compilation results in real-time
6. Continues until stopped with Ctrl+C

When to Use:

• During active development requiring immediate feedback
• Testing changes iteratively
• Rapid prototyping
• Learning Magentrix development

When Not to Use:

• Deploying multiple related changes (use publish instead)
• Working with slow internet connection
• Making structural changes across many files

Example Session:

$ magentrix autopublish

🔄 Auto-publish mode started
Watching for file changes... (Press Ctrl+C to stop)

[14:32:15] Changed: src/Controllers/HomeController.ctrl
  ✓ Uploaded
  ✓ Compiled successfully

[14:33:22] Changed: src/Pages/Dashboard.aspx
  ✓ Uploaded
  ✓ Compiled successfully

[14:34:10] Changed: src/Classes/EmailHelper.ac
  ✓ Uploaded
  ✗ Compilation error: Line 42: Missing semicolon

^C
Auto-publish stopped

Performance Note:

• Each file is uploaded individually (slower for many files)
• Server compiles after each upload
• Best for single-file changes
• For bulk changes, use publish instead

config

Purpose: Manage CLI configuration settings interactively.

Syntax:

magentrix config

Parameters: None

Interactive Menu:

? What would you like to do?
❯ Log File Settings
  View All Settings
  Cancel

Options:

1. Log File Settings

Enable or disable detailed operation logs:

? Enable operation logs?
❯ Yes - Save detailed logs for debugging
  No - Disable logging

Log Behavior:

• Enabled: Saves detailed logs to .magentrix/logs/
• Disabled: Only console output, no file logs
• Automatically keeps only 10 most recent logs per operation type

Log File Location:

.magentrix/logs/
├── pull-2024-12-11T10-30-45.log
├── publish-2024-12-11T11-15-22.log
└── autopublish-2024-12-11T14-00-00.log

2. View All Settings

Display current configuration:

Current Configuration:
  Instance URL: https://yourcompany.magentrix.com
  API Key: *****...***45a3 (masked)
  Logs Enabled: Yes
  Project Path: /Users/yourname/magentrix-project
  Last Pull: 2024-12-11 10:30:45
  Last Publish: 2024-12-11 11:15:22

When to Use:

• Enable logs when troubleshooting issues
• Verify current settings
• Check which instance you're connected to
• Disable logs for production deployments

Example:

$ magentrix config

? What would you like to do? Log File Settings
? Enable operation logs? Yes

✓ Logging enabled
Logs will be saved to: .magentrix/logs/

create

Purpose: Create new Magentrix files with proper templates locally and on the server.

Syntax:

Interactive mode:

magentrix create

Non-interactive mode:

magentrix create [options]

Interactive Mode:

The wizard guides you through file creation:

Step 1: Choose Entity Type

? What would you like to create?
❯ ActiveClass (Controller, Class, or Trigger)
  ActivePage (Page or Template)

Step 2a: For ActiveClass - Select Type

? Select class type:
❯ Controller
  Utility Class
  Trigger

Step 2b: For ActivePage - Select Type

? Select page type:
❯ Page
  Template

Step 3: Enter Name

? Enter the name: UserManagement

Step 4: Enter Description (Optional)

? Enter description (optional): Manages user accounts

Step 5: For Triggers - Select Entity

? Search for entity: contact

? Select target entity:
❯ Contact (ID: 5001)
  Contact Request (ID: 5023)
  Contact Group (ID: 5045)

Result:

✓ Creating UserManagementController.ctrl...
✓ File created locally: src/Controllers/UserManagementController.ctrl
✓ File created on server
✓ Template applied
✓ Ready for development!

Non-Interactive Mode Options:

Non-Interactive Examples:

Create a controller:

magentrix create   --type class   --class-type controller   --name UserController   --description "Handles user operations"

Create a utility class:

magentrix create   --type class   --class-type utility   --name EmailHelper   --description "Email utility functions"

Create a trigger:

magentrix create   --type class   --class-type trigger   --entity-id 5001   --name AccountTrigger   --description "Account trigger logic"

Create a page:

magentrix create   --type page   --name Dashboard   --description "Main dashboard page"

Create a template:

magentrix create   --type template   --name EmailTemplate   --description "Email notification template"

File Templates:

The CLI creates files with proper boilerplate code:

Controller Template:

public class UserController : BaseController
{
	public ActionResult Index()
	{
		return View();
	}
}

Utility Class Template:

public class EmailHelper
{
	// Add your utility methods here
}

Trigger Template:

public class AccountTrigger : ActiveTrigger<Account>
{
	// Add trigger logic
}

Page Template:

<h1>Dashboard</h1>
<p>Page content goes here</p>

publish

Purpose: Upload all local changes to the Magentrix server and compile them.

Syntax:

magentrix publish

Parameters: None

Behavior:

1. Scan Phase: Scans local src/ directory for changes
2. Analysis Phase: Compares with server state
3. Confirmation Phase: Shows changes and asks for confirmation
4. Upload Phase: Uploads changed files in parallel
5. Compilation Phase: Server compiles uploaded code
6. Report Phase: Displays results

Example Session:

$ magentrix publish

📤 Analyzing changes...

Changes to be published:
  
  Created (2):
    + src/Controllers/ReportController.ctrl
    + src/Pages/Reports.aspx
  
  Modified (3):
    ~ src/Controllers/HomeController.ctrl
    ~ src/Classes/EmailHelper.ac
    ~ src/Contents/Assets/css/main.css
  
  Deleted (1):
    - src/Pages/OldDashboard.aspx

? Proceed with publish? (Y/n) Y

📤 Publishing changes...

✓ Uploading ReportController.ctrl...
✓ Uploading Reports.aspx...
✓ Uploading HomeController.ctrl...
✓ Uploading EmailHelper.ac...
✓ Uploading main.css...
✓ Deleting OldDashboard.aspx...

✓ Compiling code on server...

✓ All changes published successfully!
  Created: 2 files
  Updated: 3 files
  Deleted: 1 file
  
Completed in 5.2 seconds

Performance Characteristics:

Change Detection:

The CLI tracks changes using:

• File modification timestamps
• Content hashing (SHA-256)
• Server state comparison

Handles:

• New files (created locally)
• Modified files (changed locally)
• Deleted files (removed locally)
• Binary files (images, etc.)
• Text files (code, CSS, etc.)

Best Practices:

1. Always run magentrix status before publish
2. Review the change list carefully
3. Test locally before publishing
4. Commit to version control before publishing
5. Publish at logical completion points

When to Use:

• Completed feature development
• End of work session
• Before switching tasks
• Deploying tested changes

When Not to Use:

• During active development (use autopublish)
• Before testing changes
• With uncommitted version control changes

⚠ Important: Publishing overwrites server files. Always run status first to review changes.

pull

Purpose: Download all files from the Magentrix server to your local machine.

Syntax:

magentrix pull

Parameters: None

Behavior:

1. Connect: Connects to Magentrix server
2. Fetch Metadata: Retrieves list of all files
3. Conflict Detection: Compares with local state
4. Download: Downloads files in batches
5. Organize: Saves files to proper directories
6. Update Cache: Updates local state tracking

Example Session (First Time):

$ magentrix pull

📥 Pulling from Magentrix...

Fetching file list...
✓ Found 125 files

Downloading files:
  Controllers... ████████████████ 15/15
  Classes...     ████████████████  8/8
  Triggers...    ████████████████  5/5
  Pages...       ████████████████ 12/12
  Templates...   ████████████████  3/3
  Assets...      ████████████████ 82/82

✓ All files downloaded successfully!

Summary:
  Controllers: 15
  Classes: 8
  Triggers: 5
  Pages: 12
  Templates: 3
  Assets: 82
  Total: 125 files

Completed in 8.3 seconds

Example Session (With Conflicts):

$ magentrix pull

📥 Pulling from Magentrix...

⚠ Conflicts detected! (3 files)

The following files have changed both locally and on the server:
  ~ src/Controllers/HomeController.ctrl
  ~ src/Classes/EmailHelper.ac
  ~ src/Pages/Dashboard.aspx

? How would you like to resolve conflicts?
❯ Overwrite Local - Replace local files with server versions
  Skip Conflicts - Keep local files, ignore server changes
  Manual Review - Review each conflict individually

Conflict Resolution Options:

Option 1: Overwrite Local

• Replaces your local files with server versions
• You lose local changes
• Use when server version is correct

Option 2: Skip Conflicts

• Keeps your local files unchanged
• Ignores server changes
• Use when local version is correct

Option 3: Manual Review

• Reviews each file individually
• Asks for resolution per file
• Allows selective overwriting

Manual Review Example:

File: src/Controllers/HomeController.ctrl

? Resolve this conflict:
❯ Use Server Version
  Keep Local Version
  Show Diff

[If "Show Diff" selected]
Local (modified 2024-12-11 10:00):
  Line 45: return View("Home");

Server (modified 2024-12-11 11:30):
  Line 45: return View("Dashboard");

? Resolve this conflict:
❯ Use Server Version
  Keep Local Version

First-Time Prompts:

The first time you run pull on a project with many files:

📋 Log File Settings

Magentrix CLI can save detailed operation logs for debugging.

? Would you like to save operation logs to files? (Y/n)

This is a one-time setup. Your choice is saved globally.

When to Use:

• Start of workday (get latest changes)
• Before making major changes (avoid conflicts)
• After teammate publishes changes
• When server files have been modified in IDE

File Organization:

Files are downloaded to:

src/
├── Classes/              ← Utility classes
├── Controllers/          ← Controllers
├── Triggers/             ← Database triggers
├── Pages/                ← ASPX pages
├── Templates/            ← ASPX templates
└── Contents/Assets/      ← Static assets

Progress Tracking:

The command shows separate progress for:

• Code entities (Controllers, Classes, Triggers, Pages, Templates)
• Static assets (CSS, JS, images, etc.)

setup

Purpose: Configure API credentials and connection settings for the Magentrix CLI.

Syntax:

Interactive mode:

magentrix setup

Non-interactive mode:

magentrix setup --api-key <key> --instance-url <url>

Interactive Mode:

$ magentrix setup

Magentrix CLI Setup
───────────────────────────────────────

? Enter your Magentrix API key: [hidden]
? Enter your Magentrix instance URL: https://yourcompany.magentrix.com

✓ Testing connection...
✓ Connection successful!
✓ Credentials saved securely
✓ VS Code file associations configured

Setup complete! Run 'magentrix pull' to download your files.

Non-Interactive Mode:

For automation or CI/CD:

magentrix setup   --api-key YOUR_API_KEY   --instance-url https://yourcompany.magentrix.com

Options:

What Setup Does:

1. Validates Credentials: Tests connection to Magentrix
2. Saves Securely: Stores credentials in system config directory
3. Creates Project Config: Initializes .magentrix/ directory
4. Configures Editor: Sets up VS Code file associations (if detected)
5. Links Project: Associates current directory with credentials

Configuration Storage:

Global Config Location:

• Mac/Linux: ~/.config/magentrix/
• Windows: %APPDATA%/magentrix/

Contains:

• API credentials (namespaced by project folder hash)
• Global preferences
• Multiple instance credentials

Project Config Location:

• .magentrix/ in project directory

Contains:

• Project-specific cache
• File mappings
• Sync state

Multiple Instance Support:

You can manage multiple Magentrix instances simultaneously:

# Production instance
mkdir ~/magentrix-production
cd ~/magentrix-production
magentrix setup
# Enter production credentials

# Development instance
mkdir ~/magentrix-development
cd ~/magentrix-development
magentrix setup
# Enter development credentials

Each folder maintains independent credentials automatically.

Security:

• API keys are stored securely in system config directories
• Keys are masked in output (*****...***45a3)
• Keys are never logged or displayed in full
• Folder-based namespacing prevents credential conflicts

When to Use:

• Initial CLI installation
• Changing API credentials
• Switching to different Magentrix instance
• After moving/renaming project folder
• Setting up new development machine

Reconfiguration:

To change credentials, simply run setup again. It will overwrite existing configuration.

status

Purpose: Compare local files with server state to identify changes, conflicts, and sync status.

Syntax:

magentrix status

Parameters: None

Behavior:

1. Scan Local Files: Scans src/ directory
2. Fetch Server State: Retrieves server file metadata
3. Compare: Identifies differences
4. Report: Displays categorized changes

Does NOT:

• Make any changes to files
• Upload anything to server
• Download anything from server
• Modify local state

Example Output (In Sync):

$ magentrix status

📊 Status Report
────────────────────────────────────

✓ All files in sync
✓ No conflicts detected
✓ No unpublished changes

Last Pull: 2024-12-11 10:30:45
Last Publish: 2024-12-11 11:15:22

Example Output (With Changes):

$ magentrix status

📊 Status Report
────────────────────────────────────

Unpublished Local Changes (5):
  
  Created (2):
    + src/Controllers/ReportController.ctrl
    + src/Pages/Reports.aspx
  
  Modified (2):
    ~ src/Controllers/HomeController.ctrl
    ~ src/Classes/EmailHelper.ac
  
  Deleted (1):
    - src/Pages/OldDashboard.aspx

Server Changes Not in Local (3):
  
  Modified (2):
    ~ src/Controllers/UserController.ctrl (server newer)
    ~ src/Pages/Profile.aspx (server newer)
  
  Created (1):
    + src/Classes/NewHelper.ac (exists on server only)

⚠ Conflicts Detected (1):
  
  ⚠ src/Controllers/HomeController.ctrl
    Both local and server have changes
    Local modified: 2024-12-11 10:15:30
    Server modified: 2024-12-11 11:00:45

Recommendations:
  1. Run 'magentrix pull' to get server changes
  2. Resolve conflicts manually
  3. Run 'magentrix publish' to upload your changes

Status Categories:

Unpublished Local Changes:

• Files created locally but not on server
• Files modified locally since last publish
• Files deleted locally but still on server

Server Changes Not in Local:

• Files created on server (via IDE or other user)
• Files modified on server since last pull
• Files deleted on server but still local

Conflicts:

• Files changed both locally and on server
• Requires manual resolution

Status Symbols:

When to Use:

• Before running publish (preview changes)
• After running pull (verify sync)
• To check for conflicts before working
• To verify current workspace state
• Before committing to version control

Workflow Example:

# Check status before starting work
magentrix status

# Make changes to files
# ...

# Check what changed
magentrix status

# Verify changes before publishing
magentrix publish

💡 Best Practice: Make status part of your workflow. Run it before publish to avoid surprises.

File Type Reference

Magentrix File Types

Understanding file types helps you use the appropriate commands and organize your code:

File Extensions and Languages

Command Comparison

When to Use Which Command

Development Workflow Commands

Daily Development Cycle:

magentrix pull          # Start: Get latest
magentrix status        # Verify: Check state
# ... make changes ...
magentrix status        # Review: Check changes
magentrix publish       # Deploy: Upload changes

Real-Time Development:

magentrix pull          # Get latest
magentrix autopublish   # Start watching
# ... edit and save files automatically uploaded ...
# Ctrl+C to stop

Feature Development:

magentrix pull          # Sync first
magentrix create        # Create files
# ... develop feature ...
magentrix status        # Review changes
magentrix publish       # Deploy feature

Advanced Usage

Non-Interactive Automation

All commands support non-interactive operation for CI/CD:

# Setup
magentrix setup   --api-key ${MAGENTRIX_API_KEY}   --instance-url ${MAGENTRIX_URL}

# Pull
magentrix pull

# Create file
magentrix create   --type class   --class-type controller   --name AutoController

# Publish
magentrix publish

Environment Variables

Store credentials securely:

export MAGENTRIX_API_KEY="your-api-key"
export MAGENTRIX_URL="https://yourcompany.magentrix.com"

magentrix setup --api-key $MAGENTRIX_API_KEY --instance-url $MAGENTRIX_URL

Scripting Examples

Daily sync script:

#!/bin/bash
cd ~/magentrix-project
magentrix pull
magentrix status

Auto-deploy script:

#!/bin/bash
cd ~/magentrix-project
magentrix status
echo "Deploying changes..."
magentrix publish

Error Messages and Solutions

Common Error Messages

Authentication Error:

✗ Authentication failed
  Invalid API key or insufficient permissions

Solution: Run magentrix setup with correct credentials

Connection Error:

✗ Cannot connect to instance
  Network error or invalid URL

Solution: Check instance URL and internet connection

File Conflict:

⚠ Conflicts detected
  Files changed both locally and on server

Solution: Run magentrix pull and resolve conflicts

Compilation Error:

✗ Compilation failed: Line 42: Missing semicolon

Solution: Fix syntax errors in code and republish

Permission Error:

✗ Permission denied
  User does not have access to create files

Solution: Contact administrator for proper permissions

Video Tutorial

[Video Placeholder: Magentrix CLI Command Reference]

This video demonstrates:

• Using each command with examples
• Understanding command output
• Common command combinations
• Troubleshooting command errors

Next Steps

Now that you understand all available commands:

1. Learn Development Workflows: See practical usage patterns

   • See: Magentrix CLI - Developer Guide

2. Review Platform Documentation: Understand Magentrix development concepts

   • Magentrix IDE
   • Working with Controllers
   • Working with Triggers

Quick Reference Card

╔══════════════════════════════════════════════════════════════╗
║              MAGENTRIX CLI QUICK REFERENCE                   ║
╠══════════════════════════════════════════════════════════════╣
║ setup              Configure credentials                     ║
║ pull               Download from server                      ║
║ status             Check sync state                          ║
║ publish            Upload to server                          ║
║ create             Create new file                           ║
║ autopublish        Auto-sync mode                            ║
║ config             Manage settings                           ║
║ --help             Show help                                 ║
║ --version          Show version                              ║
╠══════════════════════════════════════════════════════════════╣
║ DAILY WORKFLOW:                                              ║
║   magentrix pull        → Get latest                         ║
║   magentrix status      → Check state                        ║
║   [edit files]          → Make changes                       ║
║   magentrix publish     → Deploy                             ║
╚══════════════════════════════════════════════════════════════╝