> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentfront.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> Complete reference for all FrontMCP CLI commands

The `frontmcp` CLI provides commands for development, process management, and package management. Install it globally or use via `npx`.

```bash theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
frontmcp <command> [options]
```

## Development Commands

Commands for building, testing, and debugging your FrontMCP server.

| Command                | Description                                                   |
| ---------------------- | ------------------------------------------------------------- |
| `dev`                  | Start in development mode (tsx --watch + async type-check)    |
| `build`                | Build for a deployment target (defaults to `--target node`)   |
| `build --target node`  | Build distributable executable bundle (esbuild + tsc)         |
| `build --target cli`   | Build CLI executable with subcommands per tool                |
| `build --target mcpb`  | Package server as an `.mcpb` archive for MCPB-aware clients   |
| `mcpb validate <path>` | Validate a `.mcpb` archive against the MCPB v0.3 spec         |
| `test`                 | Run E2E tests with auto-injected Jest configuration           |
| `init`                 | Create or fix a tsconfig.json suitable for FrontMCP           |
| `doctor`               | Check Node/npm versions and tsconfig requirements             |
| `inspector`            | Launch MCP Inspector (`npx @modelcontextprotocol/inspector`)  |
| `create [name]`        | Scaffold a new FrontMCP project (interactive if name omitted) |
| `socket <entry>`       | Start Unix socket daemon for local MCP server                 |

***

## Process Manager Commands

Manage long-running MCP servers with automatic supervision, restart policies, and logging.

| Command                   | Description                                                       |
| ------------------------- | ----------------------------------------------------------------- |
| `start <name>`            | Start a named MCP server with supervisor                          |
| `stop <name>`             | Stop a managed server (graceful by default)                       |
| `restart <name>`          | Restart a managed server                                          |
| `status [name]`           | Show process status (detail if name given, table if omitted)      |
| `list`                    | List all managed processes                                        |
| `logs <name>`             | Tail log output for a managed server                              |
| `service <action> [name]` | Install/uninstall systemd/launchd service (optional service name) |

***

## Package Manager Commands

Install, configure, and manage MCP apps from npm, local paths, or git repositories.

| Command            | Description                                     |
| ------------------ | ----------------------------------------------- |
| `install <source>` | Install an MCP app from npm, local path, or git |
| `uninstall <name>` | Remove an installed MCP app                     |
| `configure <name>` | Re-run setup questionnaire for an installed app |

***

## Options Reference

### General Options

| Option                | Description                          |
| --------------------- | ------------------------------------ |
| `-h, --help`          | Show help message                    |
| `-o, --out-dir <dir>` | Output directory (default: `./dist`) |
| `-e, --entry <path>`  | Manually specify entry file path     |

### Build Options

| Option               | Description                                                                                            |
| -------------------- | ------------------------------------------------------------------------------------------------------ |
| `--target <target>`  | Build target: `node`, `cli`, `sdk`, `browser`, `vercel`, `lambda`, `cloudflare`, `distributed`, `mcpb` |
| `--js`               | Emit plain JavaScript bundle instead of SEA (use with `--target cli`)                                  |
| `--sea`              | Also build a single-executable binary for the host platform (use with `--target mcpb`)                 |
| `--merge-from <dir>` | Merge cross-platform SEA binaries from `{dir}/{platform}/{name}` (use with `--target mcpb`)            |
| `--icon <path>`      | Override the icon path included in the archive (use with `--target mcpb`)                              |
| `--no-deterministic` | Disable deterministic archive output (use with `--target mcpb`)                                        |
| `--stage-only`       | Leave the MCPB staging directory intact and skip zipping (use with `--target mcpb`)                    |

### Start Options

| Option                | Description                                  |
| --------------------- | -------------------------------------------- |
| `-e, --entry <path>`  | Entry file for the server                    |
| `-p, --port <N>`      | Port number for the server                   |
| `-s, --socket <path>` | Unix socket path                             |
| `--db <path>`         | SQLite database path                         |
| `--max-restarts <N>`  | Maximum auto-restart attempts (default: `5`) |

### Stop Options

| Option        | Description                             |
| ------------- | --------------------------------------- |
| `-f, --force` | Force kill (SIGKILL instead of SIGTERM) |

### Logs Options

| Option            | Description                             |
| ----------------- | --------------------------------------- |
| `-F, --follow`    | Follow log output (like `tail -f`)      |
| `-n, --lines <N>` | Number of lines to show (default: `50`) |

### Install Options

| Option             | Description                                    |
| ------------------ | ---------------------------------------------- |
| `--registry <url>` | npm registry URL for private packages          |
| `-y, --yes`        | Silent mode (use defaults, skip questionnaire) |
| `-p, --port <N>`   | Override default port                          |

### Create Options

| Option              | Description                                                                      |
| ------------------- | -------------------------------------------------------------------------------- |
| `-y, --yes`         | Use defaults (non-interactive mode)                                              |
| `--target <target>` | Deployment target: `node`, `vercel`, `lambda`, `cloudflare`                      |
| `--redis <setup>`   | Redis setup: `docker`, `existing`, `none` (node target only)                     |
| `--pm <pm>`         | Package manager: `npm`, `yarn`, `pnpm`                                           |
| `--cicd`            | Enable GitHub Actions CI/CD                                                      |
| `--no-cicd`         | Disable GitHub Actions CI/CD                                                     |
| `--nx`              | Scaffold an Nx monorepo workspace                                                |
| `--skills <bundle>` | Skills bundle: `recommended`, `minimal`, `full`, `none` (default: `recommended`) |

<Info>
  The `create` command automatically initializes a git repository and creates an initial commit after scaffolding.
  If `git` is not installed, this step is silently skipped.
</Info>

### Socket Options

| Option                | Description                                                  |
| --------------------- | ------------------------------------------------------------ |
| `-s, --socket <path>` | Unix socket path (default: `~/.frontmcp/sockets/{app}.sock`) |
| `--db <path>`         | SQLite database path for persistence                         |
| `-b, --background`    | Run as background daemon (detached process)                  |

### Test Options

| Option               | Description                                  |
| -------------------- | -------------------------------------------- |
| `-i, --runInBand`    | Run tests sequentially (recommended for E2E) |
| `-w, --watch`        | Run tests in watch mode                      |
| `-v, --verbose`      | Show verbose test output                     |
| `-t, --timeout <ms>` | Set test timeout (default: `60000ms`)        |
| `-c, --coverage`     | Collect test coverage                        |

***

## Generated Executable CLI

When you build with `--target cli`, the output is a self-contained executable whose commands are auto-generated from your MCP server's tools, resources, prompts, and templates.

### Building

```bash theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
frontmcp build --target cli
```

This produces a self-contained executable in `dist/` that can be distributed and run directly. Use `--js` to emit a plain JavaScript bundle instead.

### Global Options

| Option            | Description                                     | Default |
| ----------------- | ----------------------------------------------- | ------- |
| `--output <mode>` | Output format: `text` or `json`                 | `text`  |
| `-h, --help`      | Show grouped help (Tools, Resources, Auth, etc) | —       |
| `-V, --version`   | Print version                                   | —       |

### Command Groups

The generated CLI organizes commands into five groups:

**Tools** — Each MCP tool becomes a kebab-case subcommand. Flags are derived from the tool's input schema. Object-typed parameters accept JSON strings:

```bash theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
# Pass an object-typed parameter as JSON
./myapp create-user --profile '{"name":"Alice","role":"admin"}'
```

**Resources & Prompts** — `resource list`, `resource read <uri>`, `template list`, `template <name>`, `prompt list`, `prompt <name>`.

**Auth** — `login`, `logout`, `sessions list`, `sessions switch <name>`, `connect --token <TOKEN>`.

**Subscriptions** — `subscribe resource <uri>`, `subscribe notification <name>`.

**System** — `serve`, `daemon start|stop|status|logs`, `doctor`, `install`, `uninstall`.

### Example Session

```bash theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
# View all available commands grouped by category
./myapp --help

# Run a tool subcommand
./myapp search-users --query "alice" --limit 10

# List and read resources
./myapp resource list
./myapp resource read "file://config.json"

# Read a resource template with parameters
./myapp template user-profile --user-id 42

# OAuth login and session management
./myapp login --server https://auth.example.com
./myapp sessions list
./myapp sessions switch production

# Stream resource updates
./myapp subscribe resource "file://config.json"

# JSON output mode
./myapp search-users --query "alice" --output json
```

### Configuration

Control the generated CLI via the `cli` block on the `cli` deployment in `frontmcp.config.js`:

```js theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
module.exports = {
  name: 'myapp',
  deployments: [
    {
      target: 'cli',
      cli: {
        outputDefault: 'text',
        authRequired: false,
        description: 'My MCP CLI',
        excludeTools: [],
        oauth: {
          serverUrl: 'https://auth.example.com',
          clientId: 'my-app',
          defaultScope: 'read write',
          portRange: [17830, 17850],
        },
      },
    },
  ],
};
```

### Tool Name Conflicts

If a tool name collides with a built-in command (`login`, `logout`, `serve`, `connect`, `doctor`, `install`, `uninstall`, `resource`, `template`, `prompt`, `subscribe`, `sessions`, `daemon`, `job`, `skills`), the tool subcommand is automatically suffixed with `-tool` (e.g., `login-tool`).

***

## Examples

### Development

```bash theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
# Start dev server with hot-reload
frontmcp dev

# Build to custom output directory
frontmcp build --out-dir build

# Build distributable executable
frontmcp build --target node

# Build CLI executable with subcommands per tool
frontmcp build --target cli

# Run E2E tests sequentially
frontmcp test --runInBand

# Initialize tsconfig
frontmcp init

# Check environment
frontmcp doctor

# Launch MCP Inspector
frontmcp inspector
```

### Project Scaffolding

```bash theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
# Interactive mode
npx frontmcp create

# Use defaults (non-interactive)
npx frontmcp create my-mcp --yes

# Target Vercel deployment
npx frontmcp create my-mcp --target vercel

# Scaffold an Nx monorepo workspace
npx frontmcp create my-workspace --nx
```

### Unix Socket

```bash theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
# Start socket server
frontmcp socket ./src/main.ts --socket /tmp/my-app.sock

# Start with SQLite persistence
frontmcp socket ./src/main.ts --socket /tmp/my-app.sock --db ~/.frontmcp/data/app.sqlite
```

### Process Management

```bash theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
# Start a named server
frontmcp start my-app --entry ./src/main.ts --port 3005

# Stop a server
frontmcp stop my-app

# Tail logs
frontmcp logs my-app --follow

# Install as system service
frontmcp service install my-app
```

### Package Management

```bash theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
# Install from npm (private registry)
frontmcp install @company/my-mcp --registry https://npm.company.com

# Install from local path
frontmcp install ./my-local-app

# Install from GitHub
frontmcp install github:user/repo

# Re-configure an installed app
frontmcp configure my-app

# Uninstall
frontmcp uninstall my-app
```