CLI Reference

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:

Environment	Dashboard	API
Staging	`app.maxcare.dev`	`api.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:

Validates your authentication
Prompts for app name, slug (checked for availability), and category
Creates the app on the Max AI platform
Scaffolds a full Next.js project from the official template
Writes max-ai.app.toml with your client_id
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:

Conflict detection — Compares your local max-ai.app.toml with the server config. If they differ, prompts you to choose local or server values.
Dev server — Starts npm run dev in the current directory
Cloudflare Tunnel — Exposes your local server via a public HTTPS URL (free, no account needed)
Registration — Registers your app as a draft on the platform with the tunnel URL
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. The preferred workflow is to develop locally and test your app against the staging API at api.maxcare.dev.

Options

Option	Description
`--no-tunnel`	Skip 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.

Deploying (Beta)

App deployment via the CLI is currently in beta. The deployment workflow may change as we refine the experience.

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

Option	Description
`--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

Field	Description	Editable
`app.name`	Display name	Read-only after creation
`app.slug`	URL-safe identifier	Read-only after creation
`app.client_id`	Platform identifier	Set by CLI, do not modify
`app.category`	App category	Read-only after creation
`version.number`	Semver version	Updated on deploy
`hosting.url`	Production URL	Set before deploying
`permissions.scopes`	Required API scopes	Editable
`permissions.optional_scopes`	Optional API scopes	Editable
`listing.*`	Marketplace listing info	Editable

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 and test against the staging API at api.maxcare.dev
max-ai app dev

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

# 5. When ready, set your production URL and deploy (beta)
max-ai app deploy

# 6. Submit for review from the Developer Console

Overview

Core Concepts

Working with Appointments

Working with Patients

Building Apps

Installation

Authentication

Manual API Key

Creating an App

Example

Local Development

Options

Prerequisites

Example

Deploying (Beta)

Options

Prerequisites

Example

Configuration File

Key Fields

Typical Workflow

​Installation

​Authentication

​Manual API Key

​Creating an App

​Example

​Local Development

​Options

​Prerequisites

​Example

​Deploying (Beta)

​Options

​Prerequisites

​Example

​Configuration File

​Key Fields

​Typical Workflow

Installation

Authentication

Manual API Key

Creating an App

Example

Local Development

Options

Prerequisites

Example

Deploying (Beta)

Options

Prerequisites

Example

Configuration File

Key Fields

Typical Workflow