MagentrixCLI User Guide

A complete guide to installing and using MagentrixCLI for syncing your local development files with Magentrix cloud platform.

What is MagentrixCLI?

MagentrixCLI is a command-line tool that lets you:

• Download your Magentrix code files to work on them locally
• Upload your local changes back to Magentrix
• Create new files with proper templates
• Keep everything synchronized automatically
• Work with your favorite code editor instead of the web interface
• Deploy Vue.js (Iris) applications to your Magentrix instance

Prerequisites

Before you start, make sure you have:

1. Node.js installed (version 20 or higher)

   • Download from nodejs.org
   • Verify installation: node --version

2. Access to a Magentrix instance

   • You need the URL (e.g., https://yourcompany.magentrix.com)

3. API Key from Magentrix

   • Get this from your Magentrix administrator or system settings
   • It looks like a long string of characters

Installation

Global Installation (Recommended)

Install the package globally so you can use it from anywhere:

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

Local Installation (Alternative)

If you prefer to install it locally in your project:

npm install @magentrix-corp/magentrix-cli

Then run commands using:

npx magentrix <command>

Verify Installation

Check that the installation worked:

magentrix --version

You should see the version number displayed.

Updating the Package

To update MagentrixCLI to the latest version:

Global Installation Update

If you installed globally (recommended):

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

Or to ensure you get the absolute latest version:

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

Local Installation Update

If you installed locally in your project:

npm update @magentrix-corp/magentrix-cli

Or for the latest version:

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

Check for Updates

To see if you're running the latest version:

# Check your current version
magentrix --version

# Check the latest available version on npm
npm view @magentrix-corp/magentrix-cli version

After Updating

Your configuration and local files are preserved during updates. You don't need to run magentrix setup again unless there are breaking changes (which will be noted in release notes).

Note: It's a good practice to check for updates periodically to get the latest features, bug fixes, and performance improvements.

Multi-Instance Setup

Working with Multiple Magentrix Instances

MagentrixCLI supports managing multiple Magentrix instances simultaneously by storing credentials per-folder. This means you can have different folders for different instances, and the CLI will automatically use the correct credentials based on which folder you're in.

How It Works

The CLI uses a folder hash to associate credentials with each project directory. When you run magentrix setup in a folder, the API key and instance URL are stored globally but linked to that specific folder location.

Setting Up Multiple Instances

Example: Managing both Production and Development instances

# Set up Production instance
mkdir ~/magentrix-production
cd ~/magentrix-production
magentrix setup
# Enter production API key and URL
magentrix pull

# Set up Development instance
mkdir ~/magentrix-development
cd ~/magentrix-development
magentrix setup
# Enter development API key and URL
magentrix pull

Now you can work on both instances independently:

# Work on production
cd ~/magentrix-production
magentrix publish    # Publishes to production instance

# Work on development
cd ~/magentrix-development
magentrix publish    # Publishes to development instance

Important Notes

• Each folder maintains its own independent configuration
• Credentials are stored securely in your system's config directory
• Moving or renaming project folders will require running magentrix setup again
• You can verify which instance you're connected to by running magentrix or magentrix config

First Time Setup

Step 1: Configure Your Credentials

Interactive Setup

Run this command to set up your connection to Magentrix:

magentrix setup

You'll be prompted for:

• API Key: Paste your Magentrix API key
• Instance URL: Enter your Magentrix instance URL (like https://yourcompany.magentrix.com or any custom domain)

Non-Interactive Setup

For automation or CI/CD, you can provide credentials via command-line flags:

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

Available flags:

• --api-key <apiKey> - Your Magentrix API key
• --instance-url <instanceUrl> - Your Magentrix instance URL

The tool will test your credentials and save them securely. It will also automatically configure VS Code file associations for syntax highlighting of Magentrix file types (.ac, .ctrl, .trigger, .aspx files).

Editor Support

• VS Code (Recommended): The tool automatically sets up syntax highlighting for all Magentrix file types during setup
• Other Editors: The tool works with any text editor (Sublime Text, Atom, Vim, etc.) but you'll need to configure syntax highlighting manually
• Terminal Only: You can use the tool entirely from the command line without any editor

Step 2: Download Your Files

Pull all your existing files from Magentrix:

magentrix pull

This creates a src folder with all your files organized into:

• Classes/ - Your utility classes (.ac files)
• Controllers/ - Your controllers (.ctrl files)
• Triggers/ - Your trigger code (.trigger files)
• Pages/ - Your ASPX pages (.aspx files)
• Templates/ - Your templates (.aspx files)
• Assets/ - Your static assets (images, CSS, JavaScript, etc.)
• iris-apps/ - Your Iris Vue.js applications

Daily Usage

Check Connection Status

magentrix

What it does: Displays your current connection status, API key (masked), and Magentrix instance URL. When to use: Quick check to verify you're properly authenticated and connected to the right instance.

Configure CLI Settings

magentrix config

What it does: Opens an interactive configuration wizard where you can manage CLI settings such as:

• Log File Settings: Enable or disable detailed operation logs
• View All Settings: See your current configuration including API key (masked) and instance URL

When to use:

• To enable or disable operation logs for debugging
• To verify your current settings and credentials
• To manage CLI preferences without re-running setup

Download Latest Files from Server

magentrix pull

What it does: Downloads all ActiveClass and ActivePage records from your Magentrix server to your local src/ folder. Detects conflicts if files have been changed both locally and remotely, and prompts you to resolve them. Progress tracking shows separate steps for code entities and static assets. When to use:

• Start of your workday to get latest changes
• Before making major changes to avoid conflicts
• When teammates have made server changes you need

Note: If this is your first time running magentrix pull in a project with many files, you may be prompted about saving operation logs. This is a one-time setup that helps with debugging.

Check Status and Conflicts

magentrix status

What it does: Compares your local files with the server versions and shows you exactly what's different - which files have conflicts, what's been added, modified, or deleted. Does NOT make any changes. When to use:

• Before running publish to see what will be uploaded
• To check for conflicts without downloading anything
• To verify your local workspace is in sync with server

Upload Your Changes to Server

magentrix publish

What it does: Sends all unpublished changes from your local machine to the Magentrix server and compiles them. Shows you exactly what will be created, updated, or deleted before doing it. Processes all changes in parallel for speed. Works with both code files and static assets. Features comprehensive progress tracking with timing diagnostics for large projects. When to use:

• After you've finished making changes and want to deploy them
• At the end of your work session
• When you want to share your changes with teammates

Performance Note: The CLI uses optimized algorithms for large projects. Even with 20,000+ files, initial scanning completes in under 2 seconds.

Real-Time Development Mode

magentrix autopublish

What it does: Watches your files for changes and automatically uploads and compiles them on the server whenever you save a file. Shows compilation status and any errors in the terminal in real-time. Works with both code files and static assets. Can take some time to sync each file. When to use:

• During active development when you want immediate feedback
• When testing changes and want to see results right away
• For iterative development where you're making frequent small changes Note: Best for real-time development but slower than batch publishing. Press Ctrl+C to stop.

Creating New Files

Interactive File Creation

magentrix create

This starts an interactive wizard:

1. Choose what to create:

   • ActiveClass (for Controllers, Classes, or Triggers)
   • ActivePage (for Pages or Templates)

2. For Classes/Controllers/Triggers:

   • Select the type (Controller, Class, or Trigger)
   • Enter the name
   • Add optional description
   • For Triggers: Search and select the target entity

3. For Pages/Templates:

   • Choose Page or Template
   • Enter the name
   • Add optional description

The tool creates the file both locally and on your Magentrix server with proper templates.

Non-Interactive File Creation

For automation or scripting, you can provide all parameters via command-line flags:

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 ENTITY_ID --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"

Available flags:

• --type <type> - Entity type: class, page, or template
• --class-type <classType> - For classes: controller, utility, or trigger
• --name <name> - Name of the file to create
• --description <description> - Optional description
• --entity-id <entityId> - Required for triggers: the entity ID to attach the trigger to

Tip: You can mix interactive and non-interactive modes. For example, provide just the --name flag and the tool will prompt you for the rest.

Working with Files

File Organization

Your files are organized like this:

src/
├── Classes/         # Utility classes (*.ac files)
├── Controllers/     # Controllers (*.ctrl files)
├── Triggers/        # Trigger code (*.trigger files)
├── Pages/           # ASPX pages (*.aspx files)
├── Templates/       # Templates (*.aspx files)
├── Contents/
│   └── Assets/      # Static assets (images, CSS, JS, etc.)
└── iris-apps/       # Vue.js Iris applications (see warning below)
    └── <app-slug>/  # Each app in its own folder

⚠️ IMPORTANT: Deleting Iris Apps

NEVER manually delete folders from src/iris-apps/! Always use the magentrix iris-app-delete command to remove Iris apps. Manual deletion will cause:

• No recovery backup created (you cannot restore the app)
• App remains on the Magentrix server (orphaned)
• Cache becomes out of sync (causes errors on next publish)
• Linked Vue project not properly unlinked

Correct way to delete an Iris app:

magentrix iris-app-delete

File Extensions

• .ac - Classes
• .ctrl - Controllers
• .trigger - Triggers
• .aspx - Pages and Templates

Editing Files

1. Open any file in your favorite editor (VS Code, Sublime, etc.)
2. Make your changes
3. Save the file
4. Run magentrix publish to upload changes
   • Or use magentrix autopublish for automatic uploads

Working with Static Assets

What Are Static Assets?

Static assets are non-code files like images, CSS stylesheets, JavaScript files, and other resources that your Magentrix application uses.

Asset Organization

All static assets are stored in the src/Contents/Assets/ directory. You can organize them into subfolders:

src/Contents/Assets/
├── images/
│   ├── logo.png
│   └── banner.jpg
├── css/
│   └── custom-styles.css
└── js/
    └── helpers.js

Working with Assets

Downloading Assets

magentrix pull

Downloads all static assets from the server along with your code files. The folder structure is preserved.

Adding New Assets

1. Place your files in src/Contents/Assets/ (or a subfolder)
2. Run magentrix publish to upload them
   • Or use magentrix autopublish for automatic uploads

Updating Assets

1. Edit or replace the file locally in src/Contents/Assets/
2. Run magentrix publish to upload the updated version
   • Or use magentrix autopublish for automatic uploads

Deleting Assets

1. Delete the file from src/Contents/Assets/
2. Run magentrix publish to remove it from the server

Supported File Types

The tool supports all file types including:

• Images: .png, .jpg, .jpeg, .gif, .svg, .ico
• Stylesheets: .css
• Scripts: .js
• Documents: .pdf, .txt, .json
• Any other file type you need

Important Notes

• Assets are synced alongside code files
• Folder structures are preserved when syncing
• Large files are handled efficiently using batch operations
• Binary files (like images) are fully supported

Deploying Vue.js (Iris) Apps

MagentrixCLI supports deploying Vue.js applications (Iris apps) to your Magentrix instance. These apps are built with Vue.js and Module Federation, allowing you to create custom frontend experiences.

⚠️ CRITICAL: Always use magentrix iris-app-delete to remove Iris apps!

Never manually delete folders from src/iris-apps/. Manual deletion bypasses backups, leaves orphaned apps on the server, and corrupts the cache. See Deleting an Iris app for proper deletion.

Overview

The Iris deployment workflow:

1. Link your Vue project to the CLI
2. Build and stage the project to the CLI workspace
3. Publish to Magentrix (automatically handled by magentrix publish)

Commands

Link a Vue Project

magentrix iris-app-link

What it does: Opens an interactive menu to manage linked Vue.js projects. Projects are stored globally so they persist across Magentrix workspaces.

Options:

• --path <dir> - Specify Vue project path directly
• --unlink - Remove a linked project
• --list - Show all linked projects
• --cleanup - Remove invalid (non-existent) linked projects

Menu options:

• Link a Vue project
• View all linked projects
• Unlink a project
• Cleanup invalid projects

Build and Stage

magentrix vue-run-build

What it does: Builds a linked Vue project and copies the output to src/iris-apps/<slug>/ for publishing.

Two modes of operation:

1. From Magentrix workspace: Prompts for which Vue project to build, stages to current workspace
2. From Vue project directory: Prompts for which Magentrix workspace to stage into

Options:

• --path <dir> - Specify Vue project path directly
• --skip-build - Use existing dist/ folder without rebuilding
• --workspace <dir> - Specify Magentrix workspace path directly (when running from Vue project)

Process:

1. Select from linked projects or enter path manually
2. Run npm run build in the Vue project
3. Validate the build output
4. Copy to workspace src/iris-apps/<app-slug>/ (excludes index.html, favicon.ico)
5. Check sync status and prompt to pull if needed (required before publishing)
6. Prompt to publish to Magentrix

Vue Development Server

magentrix vue-run-dev

What it does: Starts the Vue development server with platform assets (CSS, fonts) automatically injected from your Magentrix instance.

Authentication: Uses VITE_REFRESH_TOKEN from .env.development (no CLI authentication required). This command can be run inside the Vue project directory.

Options:

• --path <dir> - Specify Vue project path
• --no-inject - Skip asset injection, just run dev server

Process:

1. Fetch platform assets from Magentrix using .env.development credentials
2. Update VITE_ASSETS in .env.development (changes are kept)
3. Run npm run dev

Delete an Iris App

magentrix iris-app-delete

What it does: Safely delete a published Iris app with automatic recovery backup.

Process:

1. Select app from list of published apps
2. Show destructive warning
3. Confirm by typing exact app slug
4. Ask if you want to unlink the Vue project
5. Create recovery backup in .magentrix/iris-backups/
6. Delete from server and local files
7. Update cache

Safety features:

• Automatic backup before deletion
• Must type slug name to confirm
• Recovery possible with iris-app-recover

Recover a Deleted App

magentrix iris-app-recover

What it does: Restore a deleted Iris app from automatic backup.

Options:

• --list - Show all available recovery backups

Process:

1. Select backup to restore (sorted by deletion time)
2. Check if linked Vue project still exists
3. Restore files to src/iris-apps/<slug>/
4. Re-link Vue project (if path exists)
5. Show warnings for edge cases
6. Optionally delete backup after recovery
7. Run magentrix publish to sync to server

Vue Project Requirements

Your Vue project needs two configuration files:

1. config.ts - App metadata (required):

// src/config.ts
export const config = {
  appSlug: "my-app",           // Required: App identifier (folder name on server)
  appName: "My Application",   // Required: Display name in navigation menu
  appDescription: "",          // Optional: App description
  appIconId: "",               // Optional: App icon ID
}

2. .env.development - Environment variables:

VITE_SITE_URL = https://yourinstance.magentrix.com
VITE_REFRESH_TOKEN = your-api-key
VITE_ASSETS = '[]'  # Injected automatically by vue-run-dev

Accepted field names in config.ts:

• Slug: appSlug, slug, or app_slug
• Name: appName, app_name, or name
• Description: appDescription or app_description
• Icon: appIconId or app_icon_id

Changing an App Slug

⚠️ Important: Changing the appSlug/slug in config.ts creates a new Iris app on Magentrix. The old app is not automatically deleted.

If you simply change the slug and run vue-run-build, you'll end up with two apps on the server - the old one becomes orphaned.

Recommended workflow for changing an app slug:

# 1. Delete the old app first (from Magentrix workspace)
cd ~/magentrix-workspace
magentrix iris-app-delete         # Select the old app, confirm deletion
                                  # This removes it from server, local files, and cache
                                  # Optionally unlink the Vue project when prompted

# 2. Change the slug in your Vue project
cd ~/my-vue-app
# Edit config.ts: change appSlug from "old-slug" to "new-slug"

# 3. Re-link the project with the new slug
magentrix iris-app-link           # Updates the linked project with new slug

# 4. Build, stage, and publish
magentrix vue-run-build           # Stages to new folder: src/iris-apps/new-slug/
# When prompted, choose to publish

What happens if you don't follow this workflow:

• Both old-slug and new-slug apps will exist on the server
• The old app remains in src/iris-apps/old-slug/ locally
• You'll need to manually delete the old app using magentrix iris-app-delete

Command Availability

In Vue project directories (detected by presence of config.ts):

• ✓ magentrix iris-app-link - Link project to CLI
• ✓ magentrix vue-run-build - Build and stage (prompts for target workspace)
• ✓ magentrix vue-run-dev - Start dev server (uses .env.development credentials)
• ✓ magentrix update - Update CLI to latest version

In Magentrix workspace directories (has .magentrix/ folder):

• ✓ All standard commands (setup, pull, publish, etc.)
• ✓ All Iris commands (vue-run-build, iris-app-delete, iris-app-recover, etc.)

Note: The setup command cannot be run inside a Vue project directory - run it from your Magentrix workspace. Commands like pull, publish, autopublish require a Magentrix workspace.

Typical Development Workflow

# First time setup
magentrix iris-app-link           # Link your Vue project

# Development (run from Vue project folder)
cd ~/my-vue-app               # Work from your Vue project
magentrix vue-run-dev             # Start dev server with platform assets
# Make changes, test locally
# Press Ctrl+C to stop

# Deployment - Option A (from Vue project folder)
cd ~/my-vue-app               # Work from your Vue project
magentrix vue-run-build     # Build and select workspace to stage into
# Prompted: "Do you want to publish to Magentrix now?" → Yes/No

# Deployment - Option B (from Magentrix workspace)
cd ~/magentrix-workspace      # Navigate to Magentrix workspace
magentrix vue-run-build --path ~/my-vue-app  # Build and stage
# Prompted: "Do you want to publish to Magentrix now?" → Yes/No
# If autopublish is running, it auto-deploys instead

# Deleting an app (from workspace)
magentrix iris-app-delete         # Select app, confirm, auto-backup created
magentrix publish             # Sync deletion to server

# Recovering a deleted app (from workspace)
magentrix iris-app-recover        # Select backup, restore files
magentrix publish             # Sync recovery to server

Real-Time Deployment

For automatic deployment during development:

# Terminal 1: Run autopublish
magentrix autopublish

# Terminal 2: Build and stage after making changes
magentrix vue-run-build
# Autopublish will detect the changes and upload automatically

Troubleshooting Iris Apps

Running vue-run-build from different locations

The vue-run-build command works from both locations:

From Vue project directory:

cd ~/my-vue-app
magentrix vue-run-build  # Prompts for which workspace to stage into

From Magentrix workspace:

cd ~/magentrix-workspace
magentrix vue-run-build  # Prompts for which Vue project to build
# Or with path: magentrix vue-run-build --path ~/my-vue-app

"No Magentrix workspaces found"

When running from a Vue project, the command looks for registered workspaces in the global config. To register a workspace:

1. Navigate to your Magentrix workspace
2. Run magentrix setup (this automatically registers it)
3. Or specify workspace manually: magentrix vue-run-build --workspace /path/to/workspace

Note: Existing workspaces are auto-registered when you run any command from them.

"Publishing Iris apps from an out-of-sync workspace is not allowed"

When running vue-run-build from a Vue project, the CLI checks if the target workspace is in sync with the server. If there are pending remote changes, you must pull first.

Why this is required:

• Prevents deployment conflicts
• Ensures your app is deployed alongside the latest server state
• Avoids overwriting changes made by other team members

To resolve:

1. Navigate to the workspace: cd /path/to/workspace
2. Pull latest changes: magentrix pull
3. Re-run vue-run-build from your Vue project

"Missing required field in config.ts: slug (appSlug)"

Your Vue project's config.ts is missing the app identifier. Add an appSlug or slug field.

"Missing required field in config.ts: appName"

Your Vue project's config.ts is missing the display name. Add an appName field.

"VITE_SITE_URL not set in .env.development"

Create a .env.development file in your Vue project with VITE_SITE_URL = https://yourinstance.magentrix.com.

"No .env.development file found"

The CLI requires a .env.development file for environment variables. Create one with:

VITE_SITE_URL = https://yourinstance.magentrix.com
VITE_REFRESH_TOKEN = your-api-key
VITE_ASSETS = '[]'

"No config.ts found"

The CLI looks for config in these locations:

• src/config.ts
• config.ts
• src/iris-config.ts
• iris-config.ts

Deleting an Iris app

To remove an Iris app:

magentrix iris-app-delete

This creates an automatic recovery backup before deletion. You can restore using magentrix iris-app-recover.

Permission errors: If you get "Permission Denied" when deleting local files:

• The app is still deleted from the server and cache
• Delete the local folder manually with: rm -rf src/iris-apps/<app-slug>
• Or use sudo: sudo rm -rf src/iris-apps/<app-slug>

Recovering a deleted app

To restore a deleted Iris app:

magentrix iris-app-recover --list  # See all available backups
magentrix iris-app-recover         # Select and restore a backup
magentrix publish              # Sync to server

Important: After recovery, you must run magentrix publish to sync the app back to the Magentrix server.

Changes not detected after vue-run-build

The CLI uses content hash tracking to detect changes. If you rebuild without changes, magentrix publish will show "All files are in sync — nothing to publish!" This is expected behavior and saves unnecessary uploads.

Duplicate apps after changing slug

If you changed the appSlug/slug in config.ts and now have two apps on the server:

1. The old app is orphaned and needs manual cleanup
2. Run magentrix iris-app-delete and select the old app to remove it
3. See Changing an App Slug for the proper workflow

Handling Conflicts

When files have changed both locally and on the server, you'll see conflict options:

Option 1: Overwrite Local

Replaces your local files with server versions (you lose local changes).

Option 2: Skip Conflicts

Keeps your local files, ignores server changes.

Option 3: Manual Review

Review each conflict individually and choose what to keep.

Tip: Always run magentrix pull before making changes to avoid conflicts.

Common Workflows

Starting Your Day

magentrix pull          # Get latest files
magentrix status        # Check what's different
# Work on your files...
magentrix publish       # Upload your changes

Real-Time Development

magentrix pull          # Get latest
magentrix autopublish   # Start auto-sync
# Edit files - they upload automatically when saved
# Press Ctrl+C to stop auto-sync

Creating New Features

magentrix create        # Create new files with wizard
# Edit the created files...
magentrix publish       # Upload when ready

Before Going Home

magentrix publish       # Make sure all changes are uploaded
magentrix status        # Verify everything is in sync

Deploying a Vue.js App

Option A: From Vue project folder

cd ~/my-vue-app               # Navigate to your Vue project
magentrix iris-app-link           # Link project (first time only)
magentrix vue-run-build     # Build and select workspace to stage into
# Prompted: "Do you want to publish to Magentrix now?" → Yes/No

Option B: From Magentrix workspace

cd ~/magentrix-workspace      # Navigate to Magentrix workspace
magentrix iris-app-link --path ~/my-vue-app  # Link project (first time only)
magentrix vue-run-build --path ~/my-vue-app  # Build and stage
# Prompted: "Do you want to publish to Magentrix now?" (unless autopublish is running)

Note: When running from a Vue project, the command prompts you to select a registered workspace. Workspaces are auto-registered when you run any command from them.

Deleting and Recovering Apps

# Delete an app (creates automatic backup)
magentrix iris-app-delete         # Select app, confirm deletion

# View available backups
magentrix iris-app-recover --list

# Recover a deleted app
magentrix iris-app-recover        # Select backup, restore
magentrix publish             # Sync recovery to server

Using Git Alongside MagentrixCLI

Important: Separate Systems

MagentrixCLI and Git are completely separate tools that don't integrate with each other. Here's how to use them together effectively:

What Each Tool Does

• MagentrixCLI: Syncs your local files with your Magentrix server (for deployment and compilation)
• Git: Tracks your code changes and syncs with your source control repository (for version control and collaboration)

Recommended Workflow

1. Set Up Both Systems

# Initialize git repository (if not already done)
git init
git remote add origin <your-repo-url>

# Set up MagentrixCLI
magentrix setup
magentrix pull

2. Daily Development Flow

# Start of day - get latest from both systems
git pull                    # Get latest code from repository
magentrix pull             # Get latest files from Magentrix server

# Work on your files...
# Save changes in editor

# Commit to git first (for version control)
git add .
git commit -m "Your commit message"
git push                   # Share with team via git

# Then deploy to Magentrix server
magentrix publish          # Deploy to server for testing/production

3. Git Repository Setup

Add these to your .gitignore file:

# MagentrixCLI cache files - don't commit these
.magentrix/
node_modules/

But DO commit:

src/                       # Your actual code files
package.json              # If you have one
README.md                 # Documentation

Best Practices

Use Git for Version Control

• Commit often: Commit logical chunks of work with meaningful messages
• Branch for features: Create branches for new features or major changes
• Code reviews: Use pull requests for team collaboration

Use MagentrixCLI for Deployment

• Test locally first: Make sure your code works before deploying
• Deploy after committing: Always commit to git before deploying to Magentrix
• Use status: Check magentrix status before deploying

Example Team Workflow

Developer A

git checkout -b feature/new-controller
# Make changes to files
git add .
git commit -m "Add new customer controller"
git push origin feature/new-controller
# Create pull request

# After PR approval and merge:
git checkout main
git pull
magentrix publish          # Deploy merged changes

Developer B

git pull                   # Get A's changes
magentrix pull            # Get any server changes
# Continue working with latest code

Conflict Resolution

Git Conflicts (Code Level)

• Resolve using git merge tools
• Coordinate with teammates
• Use standard git conflict resolution

Magentrix Conflicts (Server Level)

• Use magentrix status to identify conflicts
• Choose resolution strategy (overwrite, skip, manual)
• Independent of git - handled by MagentrixCLI

Why Keep Them Separate

• Git: Permanent history, branching, collaboration, code reviews
• MagentrixCLI: Live server deployment, compilation, testing
• Different purposes: Version control vs deployment
• Different timing: Git for development process, MagentrixCLI for deployment

This separation gives you the best of both worlds - robust version control AND seamless deployment!

Operation Logs

About Logs

MagentrixCLI can save detailed operation logs to help with debugging and troubleshooting. This is particularly useful when dealing with large projects or investigating sync issues.

Enabling/Disabling Logs

First Time Prompt

The first time you run an operation like magentrix pull or magentrix publish, you'll be asked:

📋 Log File Settings
Magentrix CLI can save detailed operation logs for debugging.

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

Your choice is saved globally and applies to all future operations.

Change Settings Later

You can change your logging preference at any time:

magentrix config

Then select "Log File Settings" from the menu to enable or disable logs.

Log File Location

When enabled, logs are saved to .magentrix/logs/ in your project folder:

.magentrix/
└── logs/
    ├── pull-2025-01-15T14-30-45.log
    ├── publish-2025-01-15T15-12-30.log
    └── autopublish-2025-01-15T16-00-00.log

What Gets Logged

Operation logs include:

• Detailed timestamps for each operation
• Warnings about unknown file types or edge cases
• Errors with full stack traces
• Information about files being processed
• API calls and responses

Viewing Logs

To view a log file:

cat .magentrix/logs/pull-2025-01-15T14-30-45.log

Or open it in your text editor.

Log Cleanup

The CLI automatically keeps only the 10 most recent log files per operation type to prevent disk space issues. Older logs are automatically deleted.

Troubleshooting

"Authentication failed"

• Check your API key is correct
• Verify your instance URL is right
• Run magentrix setup again

"No files found" or empty src folder

• Run magentrix pull to download files
• Check you have permission to access the Magentrix instance

Files not uploading

• Check file permissions
• Ensure you're in the right directory (where src folder is)
• Try magentrix status to see what's different

"File is currently compiling" message

• Wait for the current upload to finish
• The tool prevents conflicts by processing one file at a time

Lost connection during autopublish

• Press Ctrl+C to stop autopublish
• Run magentrix publish to upload any remaining changes
• Restart with magentrix autopublish

Need More Debugging Information

• Enable operation logs via magentrix config
• Run the failing operation again
• Check .magentrix/logs/ for detailed error information
• Share log files with your team or support for help

Tips & Best Practices

1. Always Pull First

Run magentrix pull before starting work to get the latest files.

2. Check Status Before Publishing

Use magentrix status to see what will change before running magentrix publish.

3. Use Autopublish for Active Development

When actively coding, magentrix autopublish saves time by auto-uploading changes.

4. Backup Important Work

The tool is reliable, but always have backups of critical code.

5. Organize Your Workspace

Keep your project folder clean and organized. The tool works best with the standard file structure.

6. Use Descriptive Names

When creating new files, use clear, descriptive names that follow your team's naming conventions.

Configuration Files

The tool creates these configuration files (you normally don't need to edit them):

Global Settings

• Location: ~/.config/magentrix/ (Mac/Linux) or %APPDATA%/magentrix/ (Windows)
• Contains:
  • API credentials and connection settings (namespaced by folder hash)
  • Global preferences like log settings
  • Multiple instance credentials (each folder has its own credentials)

Project Settings

• Location: .magentrix/ folder in your project
• Contains:
  • File mappings and sync status
  • Local cache and operation logs (if enabled)
  • Base file snapshots for conflict detection

Note: These folders are created automatically. Don't delete them unless you want to reconfigure everything. The global config supports multiple instances by storing credentials per-project folder.

Getting Help

Built-in Help

magentrix --help        # Show all commands
magentrix pull --help   # Help for specific command

Check Your Setup

magentrix               # Shows connection status
magentrix status        # Shows sync status

Common Commands Summary

• magentrix setup - Configure credentials
• magentrix config - Manage CLI settings
• magentrix pull - Download files from server
• magentrix publish - Upload local changes
• magentrix create - Create new files
• magentrix status - Check sync status
• magentrix autopublish - Auto-sync mode
• magentrix update - Update to latest version
• magentrix iris-app-link - Link Vue.js projects for deployment
• magentrix vue-run-build - Build and stage Vue.js apps
• magentrix vue-run-dev - Start Vue dev server with platform assets
• magentrix iris-app-delete - Delete an Iris app with recovery backup
• magentrix iris-app-recover - Recover a deleted Iris app

What's Next?

Once you're comfortable with basic usage:

1. Set up your preferred editor with syntax highlighting for your file types
2. Learn the autopublish workflow for faster development
3. Explore conflict resolution if you work in a team
4. Check out templates created by the create command to understand best practices
5. Deploy Vue.js apps using iris-app-link, vue-run-build, and vue-run-dev commands

Happy coding with MagentrixCLI! 🚀