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

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 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, the runCli() function implements the following decision tree:

Help Commands

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

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). This registers the MCP client for tools like Cursor or Claude and accepts flags such as --path, --cursor, and --claude.

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.

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 handles argument parsing and mode selection:

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 – Contains runCli() and printMainHelp().
• packages/mcp/src/install/index.ts – Implements runInstall() with support for custom paths and client-specific flags.
• packages/mcp/src/server.ts – Defines createMcpServer() and the stdio transport layer.
• packages/mcp/package.json – Declares the CLI binary entry point.

Practical Usage Examples

Display the help screen:

npx @kaneo/mcp --help

Run the interactive installer explicitly or implicitly:

# Explicit command

kaneo-mcp install

# Implicit (when stdin is a TTY)

kaneo-mcp

Start the MCP server manually:

kaneo-mcp serve

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

echo "some request" | kaneo-mcp

Summary

• The Kaneo command-line interface is exposed as the kaneo-mcp binary, defined in packages/mcp/package.json.
• Install mode (install/setup or default TTY behavior) runs runInstall() from 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 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, 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, 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 or startMcpServer() in 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 parses these arguments to support custom client configurations beyond the standard Cursor or Claude defaults.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}