Skip to main content
The Max AI CLI (@max-ai/cli) is the fastest way to build and deploy marketplace apps.

​
Installation

npm install -g @max-ai/cli
After installation, the max-ai command is available globally.

​
Authentication

max-ai auth login
This opens a browser window where you sign in with your Max AI developer account. The CLI stores your API key locally at ~/.max-ai/config.toml. You’ll be prompted to select an environment:
EnvironmentDashboardAPI
Stagingapp.maxcare.devapi.maxcare.dev

​
Manual API Key

For CI or headless environments, pass the key directly: 
max-ai auth login --api-key <your-key> --platform-url https://api.maxcare.dev

​
Creating an App

max-ai app init [directory]
This interactive command:
  1. Validates your authentication
  2. Prompts for app name, slug (checked for availability), and category
  3. Creates the app on the Max AI platform
  4. Scaffolds a full Next.js project from the official template
  5. Writes max-ai.app.toml with your client_id
  6. Installs dependencies

​
Example

$ max-ai app init my-billing-app

? App name: My Billing App
? App slug: my-billing-app
? Category: Billing
+ App created: my-billing-app
+ Project scaffolded
+ Dependencies installed

App created successfully!

  Directory:  /Users/you/my-billing-app
  Client ID:  app_xxxxxxxxxxxxxxxx

Get started:
  cd my-billing-app
  max-ai app dev

​
Local Development

max-ai app dev [options]
This command orchestrates your entire local development workflow:
  1. Conflict detection — Compares your local max-ai.app.toml with the server config. If they differ, prompts you to choose local or server values.
  2. Dev server — Starts npm run dev in the current directory
  3. Cloudflare Tunnel — Exposes your local server via a public HTTPS URL (free, no account needed)
  4. Registration — Registers your app as a draft on the platform with the tunnel URL
  5. Auto-install — Installs the app in your organization so you can test it immediately
Your draft app appears in the marketplace only for your organization, marked with a “Draft” badge. Other organizations cannot see it.

​
Options

OptionDescription
--no-tunnelSkip the Cloudflare tunnel (use when you have your own public URL)
--port <port>Override the dev server port (default: 3000)

​
Prerequisites

The tunnel feature requires cloudflared: 
# macOS
brew install cloudflared

​
Example

$ max-ai app dev

+ Dev server ready at http://localhost:3000
+ Tunnel: https://abc123.trycloudflare.com/admin
+ App registered on Max AI
+ App installed in your org

Your app is running!
  Local:     http://localhost:3000
  Tunnel:    https://abc123.trycloudflare.com/admin
  Listing:   https://app.maxcare.dev/marketplace/my-billing-app
  App:       https://app.maxcare.dev/apps/my-billing-app

Press Ctrl+C to stop
Open the App URL to see your app running inside the Max AI dashboard.

​
Seeding Test Data

max-ai app seed
Seeds your organization with test data (patients, appointments, encounters, claims) so your app has realistic data to work with via the API. Running it again replaces the previous test data — your real data is never affected.

​
Deploying

max-ai app deploy [options]
Deploys your app by registering the current configuration with the Max AI platform. The version is auto-incremented (patch bump) unless you specify one explicitly.

​
Options

OptionDescription
--version <version>Explicit version number (default: auto-increment patch)

​
Prerequisites

Before deploying:
  • Set hosting.url in max-ai.app.toml to your production HTTPS URL
  • Your app must be hosted and publicly accessible

​
Example

$ max-ai app deploy

+ Current live version: 1.0.0
+ Version 1.0.1 deployed!
  Dashboard: https://app.maxcare.dev/marketplace/my-billing-app

​
Configuration File

The CLI uses max-ai.app.toml as the source of truth for your app’s configuration. This file is created by max-ai app init and synced during development. 
[app]
name = "My Billing App"
slug = "my-billing-app"
client_id = "app_xxxxxxxxxxxxxxxx"
category = "billing"

[version]
number = "1.0.0"

[hosting]
url = "https://my-billing-app.fly.dev"

[permissions]
scopes = ["read:patients", "read:appointments"]
optional_scopes = ["write:patients"]

[listing]
tagline = "Streamline your billing workflow"
description = "Full app description for the marketplace page"
logo_url = ""
website_url = ""
support_url = ""
privacy_url = ""
changelog_url = ""
video_url = ""
feature_list = ["Feature 1", "Feature 2"]
screenshots = []

​
Key Fields

FieldDescriptionEditable
app.nameDisplay nameRead-only after creation
app.slugURL-safe identifierRead-only after creation
app.client_idPlatform identifierSet by CLI, do not modify
app.categoryApp categoryRead-only after creation
version.numberSemver versionUpdated on deploy
hosting.urlProduction URLSet before deploying
permissions.scopesRequired API scopesEditable
permissions.optional_scopesOptional API scopesEditable
listing.*Marketplace listing infoEditable
You can also edit your app’s configuration as TOML directly in the Developer Console.

​
Typical Workflow

# 1. Authenticate (one-time)
max-ai auth login

# 2. Create your app
max-ai app init my-app
cd my-app

# 3. Develop locally (draft visible only to your org)
max-ai app dev

# 4. Seed test data for API testing
max-ai app seed

# 5. Edit your code, test in the dashboard via the tunnel URL

# 6. When ready, set your production URL and deploy
max-ai app deploy

# 7. Submit for review from the Developer Console