Magentrix CLI - Getting Started Guide

Overview

What is Magentrix CLI?

Magentrix CLI is a command-line tool that enables developers to work with Magentrix platform code locally using their preferred development environment. The CLI bridges your local development workflow with the Magentrix cloud platform, providing seamless synchronization and deployment capabilities.

Key Capabilities:

• Download Magentrix code files for local development
• Upload local changes back to the Magentrix server
• Create new files with proper templates
• Automatic synchronization during active development
• Work with any code editor or IDE of your choice

How It Complements the Magentrix IDE

The Magentrix CLI works alongside the Magentrix IDE to give developers flexibility in their workflow:

When to Use CLI vs IDE

Use Magentrix CLI when:

• Developing complex features requiring multiple file changes
• Working with version control systems like Git
• Collaborating with a development team
• Using advanced IDE features (debugging, refactoring)
• Managing large codebases efficiently
• Automating deployment through CI/CD pipelines

Use Magentrix IDE when:

• Making quick configuration changes
• Creating or modifying database entities
• Managing security roles and permissions
• Accessing entity browsers and system tools
• Learning the Magentrix platform
• Working without local development setup

Prerequisites

Before installing Magentrix CLI, ensure you have the following:

1. Node.js (Version 20 or Higher)

The CLI requires Node.js runtime environment.

Installation:

• Download from nodejs.org
• Choose the LTS (Long Term Support) version
• Follow installation instructions for your operating system

Verification:

node --version

You should see version 20.0.0 or higher displayed.

2. Access to a Magentrix Instance

You need access to a Magentrix portal where you have development permissions.

Required Information:

• Instance URL: Your Magentrix portal URL
  • Examples:
    • https://yourcompany.magentrix.com
    • https://portal.yourcompany.com (custom domain)
• Development Permissions: Ability to create and modify code files

3. API Key from Magentrix

An API key authenticates the CLI with your Magentrix instance.

How to Obtain Your API Key:

Your Magentrix administrator can provide an API key, or if you have the necessary permissions:

1. Log into your Magentrix portal
2. Navigate to your user profile or system settings
3. Locate the API key section
4. Copy the API key (a long alphanumeric string)

⚠ Security Warning: Keep your API key confidential. Do not share it publicly or commit it to version control.

4. Understanding Magentrix File Types

Before working with the CLI, familiarize yourself with Magentrix file types:

Installation

Global Installation (Recommended)

Installing the CLI globally allows you to use the magentrix command from any directory.

npm install -g @magentrix-corp/magentrix-cli

Benefits of Global Installation:

• Access from any directory
• Simpler command syntax
• Suitable for most developers

Local Installation (Alternative)

For project-specific installations or when you don't have global npm permissions:

npm install @magentrix-corp/magentrix-cli

When using local installation, prefix commands with npx:

npx magentrix <command>

Verification

Confirm successful installation:

magentrix --version

Expected Output:

1.2.1

If you see the version number, installation was successful.

Troubleshooting Installation:

• Command not found: Ensure Node.js is properly installed and npm global bin directory is in your PATH
• Permission errors: On Mac/Linux, you may need to use sudo or configure npm to install without sudo
• Network errors: Check your internet connection and npm registry access

Initial Setup

Step 1: Configure Your Credentials

Interactive Setup (Recommended for First-Time Users)

Run the setup wizard to configure your connection:

magentrix setup

You'll be prompted for:

1. API Key: Paste your Magentrix API key

   • The key will be masked for security
   • Copy it carefully to avoid errors

2. Instance URL: Enter your Magentrix portal URL

   • Include the full URL with https://
   • Examples: https://yourcompany.magentrix.com

Example Session:

? Enter your Magentrix API key: ************************************
? Enter your Magentrix instance URL: https://yourcompany.magentrix.com

✓ Testing connection...
✓ Connection successful!
✓ Credentials saved securely
✓ VS Code syntax highlighting configured

The tool validates your credentials and saves them securely in your system configuration directory.

Non-Interactive Setup (For Automation)

For CI/CD pipelines or scripted environments, provide credentials via command-line flags:

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

Available Flags:

Step 2: Editor Configuration

VS Code (Recommended)

The CLI automatically configures VS Code for Magentrix file types during setup:

Configured File Associations:

• .ac → C# syntax highlighting
• .ctrl → C# syntax highlighting
• .trigger → C# syntax highlighting
• .aspx → HTML syntax highlighting

Manual Configuration (if needed):

If automatic configuration fails, add this to your VS Code settings.json:

{
	"files.associations": {
		"*.ac": "csharp",
		"*.ctrl": "csharp",
		"*.trigger": "csharp",
		"*.aspx": "html"
	}
}

Other Editors

The CLI works with any text editor:

Supported Editors:

• Sublime Text
• Atom
• Vim/Neovim
• Visual Studio
• JetBrains IDEs (Rider, WebStorm)
• Any text editor with syntax highlighting support

Manual Configuration Required: Configure file associations in your editor's settings to associate Magentrix file extensions with the appropriate language modes.

Terminal-Only Workflow

You can use the CLI entirely from the command line without any editor if you prefer:

• Use command-line editors like nano, vi, or emacs
• Edit files with command-line tools
• View files with cat, less, or similar utilities

Step 3: Download Your Files

Pull all existing files from your Magentrix instance:

magentrix pull

What Happens:

1. The CLI connects to your Magentrix instance
2. Downloads all ActiveClass files (Controllers, Classes, Triggers)
3. Downloads all ActivePage files (Pages, Templates)
4. Downloads all static assets
5. Organizes files into the local file structure

Expected Output:

📥 Pulling from Magentrix...

✓ Downloaded 15 Controllers
✓ Downloaded 8 Classes
✓ Downloaded 5 Triggers
✓ Downloaded 12 Pages
✓ Downloaded 3 Templates
✓ Downloaded 45 Assets

✓ All files synced successfully!

Understanding the Local File Structure

After running magentrix pull, you'll see this directory structure:

your-project-folder/
├── src/
│   ├── Classes/              # Utility classes (*.ac)
│   │   ├── EmailHelper.ac
│   │   ├── DataValidator.ac
│   │   └── ...
│   ├── Controllers/          # Controllers (*.ctrl)
│   │   ├── HomeController.ctrl
│   │   ├── UserController.ctrl
│   │   └── ...
│   ├── Triggers/             # Database triggers (*.trigger)
│   │   ├── AccountTrigger.trigger
│   │   ├── ContactTrigger.trigger
│   │   └── ...
│   ├── Pages/                # ASPX pages (*.aspx)
│   │   ├── Dashboard.aspx
│   │   ├── Profile.aspx
│   │   └── ...
│   ├── Templates/            # ASPX templates (*.aspx)
│   │   ├── MainLayout.aspx
│   │   ├── EmailTemplate.aspx
│   │   └── ...
│   └── Contents/
│       └── Assets/           # Static assets
│           ├── css/
│           ├── js/
│           ├── images/
│           └── ...
└── .magentrix/               # CLI configuration (do not edit)
    ├── cache/
    └── logs/

Quick Start Workflows

Your First Day with Magentrix CLI

Follow this workflow to get comfortable with the CLI:

1. Verify Connection

magentrix

Expected Output:

✓ Connected to: https://yourcompany.magentrix.com
✓ API Key: *****...***45a3 (masked)
✓ Project: /Users/yourname/magentrix-project

2. Check Current Status

magentrix status

Expected Output:

✓ All files in sync
No conflicts detected

3. Make Your First Change

Open any file in your editor:

# Example: Edit a controller
code src/Controllers/HomeController.ctrl

Make a small change (add a comment, modify text).

4. Publish Your Change

magentrix publish

What Happens:

1. CLI analyzes changes
2. Shows you what will be uploaded
3. Asks for confirmation
4. Uploads and compiles files on the server

Example Output:

📤 Publishing changes...

Changes to be published:
  Modified: src/Controllers/HomeController.ctrl

? Proceed with publish? (Y/n) Y

✓ Uploading HomeController.ctrl...
✓ Compiling on server...
✓ Published successfully!

Congratulations! You've completed your first development cycle with Magentrix CLI.

Making Your First File

Create a new controller using the CLI:

magentrix create

Interactive Wizard:

1. Choose what to create:

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

2. Select class type:

   ? Select class type:
   ❯ Controller
     Utility Class
     Trigger
   

3. Enter name:

   ? Enter the name: TestController
   

4. Add description (optional):

   ? Enter description (optional): My first test controller
   

5. Confirmation:

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

The CLI creates a properly templated file both locally and on the server.

Publishing Your First Update

After creating or modifying files:

magentrix publish

The CLI will:

1. Scan for local changes
2. Show you what's different
3. Ask for confirmation
4. Upload to the server
5. Trigger server-side compilation
6. Report success or errors

Video Tutorial

This video covers:

• Installing Node.js and the CLI
• Setting up credentials
• Downloading files
• Making your first change
• Publishing updates
• Understanding the file structure

Next Steps

Now that you have Magentrix CLI installed and configured:

1. Explore the Command Reference: Learn about all available commands and their options

   • See: Magentrix CLI - Command Reference

2. Learn Developer Workflows: Understand daily development patterns and best practices

   • See: Magentrix CLI - Developer Guide

3. Review Magentrix IDE Documentation: Understand entity management and system tools

   • See: Magentrix IDE Overview

Troubleshooting Initial Setup

Installation Issues

Problem: npm: command not found

Solution: Node.js is not installed or not in your PATH

# Verify Node.js installation
which node

# If not found, download and install from nodejs.org

Problem: Permission denied during global installation

Solution: Configure npm to install globally without sudo (Mac/Linux)

# Create npm global directory
mkdir ~/.npm-global

# Configure npm to use new directory
npm config set prefix '~/.npm-global'

# Add to PATH in ~/.profile or ~/.zshrc
export PATH=~/.npm-global/bin:$PATH

# Reload profile
source ~/.profile

# Retry installation
npm install -g @magentrix-corp/magentrix-cli

Problem: EACCES permissions errors (Windows)

Solution: Run command prompt as Administrator or use local installation

Connection Issues

Problem: Authentication failed

Solutions:

1. Verify API key is correct (copy carefully)
2. Check instance URL includes https://
3. Confirm your user has API access permissions
4. Contact your Magentrix administrator

# Reconfigure credentials
magentrix setup

Problem: Cannot connect to instance

Solutions:

1. Verify instance URL is correct
2. Check internet connection
3. Verify Magentrix instance is accessible in browser
4. Check for firewall or proxy blocking the connection

Problem: No files found after magentrix pull

Solutions:

1. Verify you have development permissions
2. Check if your instance has any code files
3. Review error messages for details

# Enable detailed logs for debugging
magentrix config
# Select "Log File Settings" → "Enable"

# Retry pull and check logs
magentrix pull
cat .magentrix/logs/pull-*.log

Editor Configuration Issues

Problem: Syntax highlighting not working in VS Code

Solution: Manually add file associations

1. Open VS Code settings (Cmd/Ctrl + ,)
2. Search for "files.associations"
3. Click "Edit in settings.json"
4. Add:

{
	"files.associations": {
		"*.ac": "csharp",
		"*.ctrl": "csharp",
		"*.trigger": "csharp",
		"*.aspx": "html"
	}
}

Getting Help

Built-in Help

Access help for any command:

# General help
magentrix --help

# Command-specific help
magentrix pull --help
magentrix create --help

Check Configuration

View your current settings:

# Connection status
magentrix

# Detailed configuration
magentrix config

Community Resources

• Magentrix Developer Guide: help.magentrix.com/wikis/devguide
• Support Portal: Contact Magentrix support through your instance
• Release Notes: Check npm package page for updates

Contact Support

If you encounter issues:

1. Enable operation logs:

   magentrix config
   # Select "Log File Settings" → "Enable"
   

2. Reproduce the issue

3. Locate log files:

   ls .magentrix/logs/
   

4. Share log files with Magentrix support

Summary

You've learned:

• ✓ What Magentrix CLI is and how it complements the IDE
• ✓ Prerequisites for installation
• ✓ How to install and verify the CLI
• ✓ How to configure credentials
• ✓ How to set up your editor
• ✓ How to download files from Magentrix
• ✓ How to make your first change and publish it
• ✓ How to create new files
• ✓ Where to get help

You're ready to start developing with Magentrix CLI!

Continue to the Command Reference to learn about all available commands and their options.