# How to Use the Kaneo Command-Line Interface (CLI): Commands, Options, and Examples

> Master the Kaneo CLI with our guide. Learn essential commands, options, and real-world examples for efficient MCP server management. Install, serve, and get help with ease.

- Repository: [kaneo.app/kaneo](https://github.com/usekaneo/kaneo)
- Tags: how-to-guide
- Published: 2026-08-08

---

**The Kaneo CLI (`kaneo-mcp`) automatically switches between an interactive installer and an MCP server based on TTY detection, while explicit commands like `install`, `serve`, or `help` override this default behavior.**

The Kaneo command-line interface provides a unified entry point for configuring and running the Model Context Protocol (MCP) implementation. Located in the `usekaneo/kaneo` repository, the CLI is defined in [`packages/mcp/src/cli.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/src/cli.ts) and exported as the `kaneo-mcp` binary, offering a "run-or-install" experience that adapts to your environment.

## CLI Commands and Options

The Kaneo CLI recognizes specific arguments to trigger distinct behaviors. According to the source code in [`packages/mcp/src/cli.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/src/cli.ts), the `runCli()` function implements the following decision tree:

### Help Commands

Use `-h`, `--help`, or `help` to display usage information via the `printMainHelp()` function.

```bash
kaneo-mcp --help
kaneo-mcp help

```

### Installation Commands

The `install` or `setup` commands launch the interactive installer via `runInstall()` (exported from [`packages/mcp/src/install/index.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/src/install/index.ts)). This registers the MCP client for tools like Cursor or Claude and accepts flags such as `--path`, `--cursor`, and `--claude`.

```bash
kaneo-mcp install
kaneo-mcp setup --cursor

```

### Server Commands

The aliases `serve`, `server`, `stdio`, or `run` start the MCP server using `startMcpServer()`. This mode communicates over `StdioServerTransport` as implemented in [`packages/mcp/src/server.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/src/server.ts).

```bash
kaneo-mcp serve
kaneo-mcp server

```

## Default Behavior and TTY Detection

When invoked without arguments, the Kaneo CLI inspects `input.isTTY` to determine the execution path:

- **Interactive Terminal (TTY):** Runs the installer automatically (`await runInstall([])`), guiding users through MCP client registration.
- **Piped Input (non-TTY):** Starts the MCP server immediately (`await startMcpServer()`), enabling tools to communicate via stdio.

This logic ensures that running `kaneo-mcp` alone in a terminal launches the setup wizard, while piping data into the process (e.g., from Cursor or Claude) triggers server mode without user intervention.

## Implementation Architecture

The CLI's entry point in [`packages/mcp/src/cli.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/src/cli.ts) handles argument parsing and mode selection:

```typescript
export async function runCli(): Promise<void> {
  const argv = process.argv.slice(2);

  if (argv[0] === "-h" || argv[0] === "--help" || argv[0] === "help") {
    printMainHelp();
    return;
  }

  if (argv[0] === "install" || argv[0] === "setup") {
    await runInstall(argv.slice(1));
    return;
  }

  if (argv[0] !== undefined) {
    if (SERVE_ALIASES.has(argv[0])) {
      await startMcpServer();
      return;
    }
    console.error(`Unknown command: ${argv[0]}`);
    printMainHelp();
    process.exitCode = 1;
    return;
  }

  if (input.isTTY) {
    await runInstall([]);
    return;
  }
  await startMcpServer();
}

```

**Key implementation files:**
- **[`packages/mcp/src/cli.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/src/cli.ts)** – Contains `runCli()` and `printMainHelp()`.
- **[`packages/mcp/src/install/index.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/src/install/index.ts)** – Implements `runInstall()` with support for custom paths and client-specific flags.
- **[`packages/mcp/src/server.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/src/server.ts)** – Defines `createMcpServer()` and the stdio transport layer.
- **[`packages/mcp/package.json`](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/package.json)** – Declares the CLI binary entry point.

## Practical Usage Examples

Display the help screen:

```bash
npx @kaneo/mcp --help

```

Run the interactive installer explicitly or implicitly:

```bash

# Explicit command

kaneo-mcp install

# Implicit (when stdin is a TTY)

kaneo-mcp

```

Start the MCP server manually:

```bash
kaneo-mcp serve

```

Invoke via pipe for programmatic access (detects non-TTY stdin):

```bash
echo "some request" | kaneo-mcp

```

## Summary

- The Kaneo command-line interface is exposed as the `kaneo-mcp` binary, defined in [`packages/mcp/package.json`](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/package.json).
- **Install mode** (`install`/`setup` or default TTY behavior) runs `runInstall()` from [`packages/mcp/src/install/index.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/src/install/index.ts) to configure MCP clients.
- **Server mode** (`serve`/`server`/`stdio`/`run` or default non-TTY behavior) executes `startMcpServer()` using `StdioServerTransport`.
- The `runCli()` function in [`packages/mcp/src/cli.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/src/cli.ts) implements the decision logic, handling `--help`, installation flags, and TTY detection.
- Unknown commands trigger an error and display the help text via `printMainHelp()`.

## Frequently Asked Questions

### What is the difference between `kaneo-mcp install` and `kaneo-mcp serve`?

The `install` command launches an interactive installer that registers the MCP client with tools like Cursor or Claude, writing wrapper scripts to forward stdio traffic. The `serve` command (and its aliases) immediately starts the MCP server to accept requests over stdio transport. According to the source code in [`packages/mcp/src/cli.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/src/cli.ts), these map to `runInstall()` and `startMcpServer()` respectively.

### How does the Kaneo CLI detect whether to run the installer or the server?

The CLI checks `input.isTTY` in the default path of `runCli()`. If stdin is a TTY (interactive terminal), it runs the installer; if stdin is piped (non-TTY), it starts the server automatically. This allows the same binary to function as both a setup tool and a headless server.

### Where is the Kaneo CLI entry point defined in the source code?

The entry point is [`packages/mcp/src/cli.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/src/cli.ts), which exports the `runCli()` function. This file handles argument parsing, help text display via `printMainHelp()`, and delegates to `runInstall()` in [`packages/mcp/src/install/index.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/src/install/index.ts) or `startMcpServer()` in [`packages/mcp/src/server.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/src/server.ts) based on the parsed commands.

### Can I use the Kaneo CLI with custom MCP client paths?

Yes. When running `kaneo-mcp install` or `kaneo-mcp setup`, the installer accepts a `--path` flag to specify custom installation locations. The `runInstall()` function in [`packages/mcp/src/install/index.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/src/install/index.ts) parses these arguments to support custom client configurations beyond the standard Cursor or Claude defaults.