> ## 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.

# CLI Reference

> Create, develop, and deploy Max AI apps from the command line

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

## Installation

```bash theme={null}
npm install -g @max-ai/cli
```

After installation, the `max-ai` command is available globally.

## Authentication

```bash theme={null}
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:

```bash theme={null}
max-ai auth login --api-key <your-key> --platform-url https://api.maxcare.dev
```

## Creating an App

```bash theme={null}
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

```bash theme={null}
$ 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

```bash theme={null}
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.

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](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/):

```bash theme={null}
# macOS
brew install cloudflared
```

### Example

```bash theme={null}
$ 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)

<Info>
  App deployment via the CLI is currently in **beta**. The deployment workflow may change as we refine the experience.
</Info>

```bash theme={null}
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

```bash theme={null}
$ 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.

```toml theme={null}
[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

```bash theme={null}
# 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
```