IRIS App CLI Reference

Overview

The Magentrix CLI (@magentrix-corp/magentrix-cli) is the primary tool for linking Vue projects, running the development server, building, publishing, and managing the full lifecycle of IRIS Apps. All deployment operations must go through the CLI.

Installation

Install globally (recommended):

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

Or install locally in your project:

npm install @magentrix-corp/magentrix-cli

With a local installation, prefix all commands with npx:

npx magentrix <command>

Verify installation:

magentrix --version

Update to the latest version:

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

or

magentrix update

First-Time Setup

Step 1 — Configure Credentials

Run the setup wizard from your Magentrix workspace directory:

magentrix setup

You will be prompted for your API Key and instance URL. For CI/CD automation, supply credentials directly as flags:

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

The CLI stores credentials per-folder. To manage multiple Magentrix instances, run magentrix setup in separate workspace directories.

Step 2 — Pull Files

Download your existing server files into the workspace:

magentrix pull

This creates the following directory structure under src/:

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

Vue Project Configuration

Every IRIS App Vue project requires two configuration files.

src/config.ts — App Metadata

export const config = {
	appSlug: "my-app",
	appName: "My Application",
	appDescription: "",
	appIconId: ""
}

The CLI searches for the config file in these locations in order: src/config.ts, config.ts, src/iris-config.ts, iris-config.ts.

.env.development — Environment Variables

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

VITE_ASSETS is automatically populated by magentrix vue-run-dev with portal CSS, font paths, and theme styles. Do not set this value manually.

Command Reference

magentrix setup

Configures CLI credentials for the current workspace directory. Stores the API key and instance URL locally. Run this once per workspace directory.

magentrix setup

# Non-interactive (CI/CD)
magentrix setup --api-key YOUR_API_KEY --instance-url https://yourcompany.magentrix.com

magentrix pull

Downloads all files from the Magentrix instance into the local src/ directory. Always run pull before making changes, especially when working in a team.

magentrix pull

magentrix publish

Pushes local file changes to the Magentrix server. Detects changes using content hash tracking — unchanged files are skipped. Used to deploy changes to controllers (.ctrl), utility classes (.ac), triggers, and staged IRIS App bundles to your Magentrix portal.

magentrix publish

After publishing changes (controllers, utility classes), hard refresh the browser to clear cached responses:

• Windows / Linux:Ctrl+Shift+R
• macOS:Cmd+Shift+R

magentrix autopublish

Watches the workspace for file changes and publishes automatically whenever a change is detected. Used together with magentrix vue-run-build for a real-time deployment workflow.

# Terminal 1 — start autopublish watcher
magentrix autopublish

# Terminal 2 — build and stage after making changes
magentrix vue-run-build
# Autopublish detects staged changes and uploads automatically

magentrix iris-app-link

Manages the link between a Vue.js project and the CLI. Linked projects are stored globally and persist across workspaces.

magentrix iris-app-link

Without flags, opens an interactive menu with options to link a Vue project, view all linked projects, unlink a project, and clean up invalid projects.

magentrix vue-run-dev

Starts the Vue development server with portal assets (CSS, fonts, theme variables) automatically injected from your Magentrix instance. This is the only correct way to start the dev server — running npm run dev directly bypasses asset injection and leaves all --mag-* CSS variables undefined.

magentrix vue-run-dev

This command uses VITE_REFRESH_TOKEN from .env.development for authentication. It can be run from the Vue project directory without CLI credentials configured for the workspace.

Process on each run:

1. Fetches portal stylesheet URLs from the Magentrix instance using .env.development credentials
2. Writes the URLs into VITE_ASSETS in .env.development
3. Runs npm run dev

magentrix vue-run-build

Builds a linked Vue project and copies the output bundle into src/iris-apps/<app-slug>/ in the Magentrix workspace, ready for publishing.

magentrix vue-run-build

This command works from two locations:

• From the Magentrix workspace — prompts for which linked Vue project to build and stages the output into the current workspace
• From the Vue project directory — prompts for which Magentrix workspace to stage into

Build 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 src/iris-apps/<app-slug>/ — excludes index.html and favicon.ico
5. Check workspace sync status and prompt to pull if out of sync
6. Prompt to publish to Magentrix

magentrix iris-app-delete

Safely deletes a published IRIS App. Automatically creates a recovery backup before deletion.

magentrix iris-app-delete

Process:

1. Select the app from the list of published apps
2. Review the destructive action warning
3. Confirm by typing the exact app slug
4. Optionally unlink the associated Vue project
5. Create a recovery backup in .magentrix/iris-backups/
6. Delete from the server and local files
7. Update the cache

magentrix iris-app-recover

Restores a deleted IRIS App from its automatic backup.

magentrix iris-app-recover

Process:

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

Workflows

First-Time Project Setup

# 1. Create the Vue project from the template
npm create @magentrix-corp/iris-app-template@latest
cd <my-app>
npm install

# 2. Link the Vue project to the CLI (one-time)
magentrix iris-app-link

# 3. Start the dev server
magentrix vue-run-dev

Daily Development

cd ~/my-vue-app
magentrix vue-run-dev     # Start dev server with portal assets injected
# Make changes and test locally
# Ctrl+C to stop

Deploying an IRIS App

Option A — from the Vue project directory:

cd ~/my-vue-app
magentrix vue-run-build
# Prompted: "Do you want to publish to Magentrix now?" → Yes

Option B — from the Magentrix workspace:

cd ~/magentrix-workspace
magentrix vue-run-build --path ~/my-vue-app
# Prompted: "Do you want to publish to Magentrix now?" → Yes

Deploying Files (Controllers, Utility Classes)

cd ~/magentrix-workspace
magentrix pull            # Always pull first
# Make changes to .ctrl or .ac files
magentrix publish         # Push changes to server
# Hard refresh browser: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (macOS)

Real-Time Deployment with Autopublish

# Terminal 1 — start watcher
magentrix autopublish

# Terminal 2 — build and stage; autopublish picks up the change
magentrix vue-run-build

Changing an App Slug

Changing appSlug in config.ts creates a brand new app on the server — it does not rename the existing one. Follow this workflow to rename correctly:

# 1. Delete the old app (creates a backup automatically)
cd ~/magentrix-workspace
magentrix iris-app-delete     # Select the old app and confirm

# 2. Update appSlug in your Vue project's src/config.ts

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

# 4. Build and publish under the new slug
magentrix vue-run-build       # Stages to: src/iris-apps/new-slug/

If you change the slug without following this workflow, both the old and new apps will exist on the server. Use magentrix iris-app-delete to remove the orphaned old app.

Troubleshooting

What to Read Next