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

An app registered by `frontmcp install` starts by name (`frontmcp start my-app`) from its install directory, using the installed bundle, the `.env` the installer wrote and the port chosen at install time. Pass `--entry` to run a different file instead.

***

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

`install` accepts a project directory, its `dist/` folder or a per-target folder such as `dist/node` (the manifest is searched in all of them; a directory holding a `frontmcp.config.*` is installed after `npm install` when it has no `node_modules`). It installs the runtime packages the bundle keeps external (for example `@frontmcp/sdk`) at the versions the project depends on, plus any native addons the manifest lists.

***

## Plugin Commands (issue #411)

Emit the current FrontMCP server as a plugin for an AI tool. Today supports
Claude Code (`.claude/plugins/<name>/`) and Codex (`~/.codex/config.toml`).

| Command | Description |
| - | - |
| `plugin install --claude` / `--codex` | Emit a Claude Code plugin folder and/or Codex `mcp_servers` entry |
| `plugin uninstall --claude` / `--codex` | Remove what `plugin install` wrote, preserving any user files |
| `plugin status --claude` / `--codex` | Report install state per provider (installed v X / outdated / missing) |

Flags shared across the three subcommands:

| Flag | Description |
| - | - |
| `--scope <s>` | `project` (default → `./.claude/plugins/`) or `user` (→ `~/.claude/plugins/`) |
| `--dir <path>` | Override the plugin destination root (testing or non-standard installs) |
| `--no-skills` | Skip the `skills/` subtree |
| `--no-commands` | Skip the `commands/` subtree |
| `--only-mcp` | Skip the plugin folder; just write the `mcpServers` entry |
| `--command <cmd>` | Override the MCP server invocation in the plugin manifest |
| `--env <NAME>` | Surface an env-var placeholder in the plugin (repeatable) |
| `--dry-run` | Print the plan; do not write |

**End-user path (built bin):** every CLI built with `frontmcp build --target cli`
inherits `install -p claude|codex` AND `uninstall -p claude|codex`. Pass `-p`
(repeatable) plus the same scope flags above to get the same plugin emit (or
removal) from the installed binary — the bin reads its sibling
`bin-meta.json` and `_skills/` tree, no SDK boot or schema extraction required
at install time.

```bash theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
# Dev-time: from a FrontMCP project root
frontmcp plugin install --claude
frontmcp plugin install --codex --dry-run
frontmcp plugin status --claude

# End-user: from the installed bin
my-bin install -p claude -p codex
my-bin install --status
my-bin uninstall -p claude          # remove the Claude plugin tree
my-bin uninstall -p claude -p codex # remove both providers in one shot
```

**SKILL.md frontmatter is synthesized from `@Skill` metadata.** When a server
ships `@Skill({ name, description, tags, license, instructions: { file } })`
entries, the install flow composes proper YAML frontmatter from the decorator
fields (so Claude Code's filesystem loader can index the skill) and copies
the instruction file body verbatim. If the source body already starts with a
`---` frontmatter block, it is preserved as-is — the user's authoring is
treated as authoritative.

***

## 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`) |
| `--no-clean` | Keep whatever is already in the output directory instead of clearing it first |

#### Output directory is cleared on every build

`frontmcp build` removes the target's output directory before compiling, so
`dist/<target>/` only ever contains what the current source set emits. Deleting
a source file therefore also removes its compiled output, and a local build
matches what CI produces from a clean checkout.

Pass `--no-clean` to keep the previous contents (useful for incremental
workflows). Cleaning is skipped automatically — with a warning — when the
resolved output directory is the project root, a parent of it, or outside the
project entirely, so a stray `outDir` can never delete your sources.

#### TypeScript is run from the project, not through `npx`

The compiler is resolved from the project's own `typescript` install and
spawned with the current Node binary, so the project's module resolver stays
active. This matters for Yarn Plug'n'Play, where a bare `npx tsc` starts a
process without `.pnp.cjs` and every entry in `compilerOptions.types` fails to
resolve (`TS2688`). When the project has no local `typescript`, the build falls
back to the package manager's own runner (`yarn tsc`, `pnpm exec tsc`,
`bun x tsc`, `npx -y tsc`) selected from the lockfile.

### 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 |
| `--no-env` | Skip `.env` / `.env.local` loading |

#### `.env` is loaded, exactly as `frontmcp dev` loads it

`frontmcp test` reads `.env` and `.env.local` into the environment before
spawning Jest, so a spec reading `process.env.MY_API_KEY` sees the same value
the dev server does. Precedence matches `dev`: the real environment wins over
the files, so CI secrets still override a local `.env`, and config overlays
(`env.shared` + `env.test` in `frontmcp.config.*`) sit underneath both.

Pass `--no-env` for a hermetic run that must not see local credentials.

***

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.