Documentation Index
Fetch the complete documentation index at: https://docs.maxcare.ai/llms.txt
Use this file to discover all available pages before exploring further.
The Max AI CLI (@max-ai/cli) is the fastest way to build and deploy marketplace apps.
Installation
npm install -g @max-ai/cli
max-ai command is available globally.
Authentication
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]
- 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
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
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]
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 |
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
