CLI Reference

The FlowMCP CLI is a command-line tool for developing, validating, and managing FlowMCP schemas. It handles schema imports, group management, live API testing, and can run as an MCP server for AI agent integration.

Installation

npm install -g flowmcp-cli

Or clone and link locally:

git clone https://github.com/FlowMCP/flowmcp-cli.git
cd flowmcp-cli
npm install
npm link

Architecture

The CLI operates on two configuration levels:

Level	Path	Content
Global	`~/.flowmcp/`	Config, `.env` with API keys, all imported schemas
Local	`{project}/.flowmcp/`	Project config, groups with selected tools

~/.flowmcp/
├── config.json          # Global configuration
├── .env                 # API keys for schema testing
└── schemas/             # All imported schema files
    └── flowmcp-schemas/ # Imported from GitHub

{project}/.flowmcp/
├── config.json          # Project-level configuration
└── groups/              # Tool groups for this project

Two Modes

The CLI has two operating modes that control which commands are available:

Mode	Default	Description
Agent	Yes	Subset of commands for AI agent use (search, add, remove, list, call, run)
Dev	No	All commands including validation, testing, schema browsing, and imports

Switch modes with flowmcp mode agent or flowmcp mode dev.

Agent mode is the default. It exposes only the commands an AI agent needs to discover, activate, and call tools. Switch to Dev mode for schema development and validation workflows.

Commands

Setup

`flowmcp init`

Interactive setup that creates global and local configuration. Run this once in each project.

flowmcp init

This will:

Create ~/.flowmcp/ if it does not exist
Optionally import the default schema repository
Create .flowmcp/ in the current project
Set up a default group

`flowmcp status`

Show config, sources, groups, and health info.

flowmcp status

`flowmcp mode [agent|dev]`

Show or switch the current mode.

flowmcp mode        # Show current mode
flowmcp mode dev    # Switch to dev mode
flowmcp mode agent  # Switch to agent mode

Discovery

`flowmcp search <query>`

Find available tools by keyword. Returns matching tool names with descriptions.

flowmcp search etherscan
flowmcp search "gas price"
flowmcp search defi

`flowmcp schemas`

List all available schemas and their tools. Dev mode only.

flowmcp schemas

The schemas command can produce long output with large schema collections. Use search first to narrow down results.

Schema Management

`flowmcp add <tool-name>`

Activate a tool for this project. Adds it to the default group.

flowmcp add coingecko_simplePrice

`flowmcp remove <tool-name>`

Deactivate a tool from the project.

flowmcp remove coingecko_simplePrice

`flowmcp list`

Show all active tools in the current project.

flowmcp list

`flowmcp import <url> [--branch name]`

Import schemas from a GitHub repository. Dev mode only.

flowmcp import https://github.com/FlowMCP/flowmcp-schemas
flowmcp import https://github.com/FlowMCP/flowmcp-schemas --branch develop

`flowmcp import-registry <url>`

Import schemas from a registry URL. Dev mode only.

flowmcp import-registry https://registry.example.com/schemas

`flowmcp update [source-name]`

Update schemas from remote registries using hash-based delta sync.

flowmcp update                    # Update all sources
flowmcp update flowmcp-schemas    # Update specific source

Group Management

Groups organize tools into named collections. Each project can have multiple groups with one set as default.

`flowmcp group list`

List all groups and their tool counts.

flowmcp group list

`flowmcp group append <name> --tools "refs"`

Add tools to a group. Creates the group if it does not exist.

flowmcp group append crypto --tools "flowmcp-schemas/coingecko/simplePrice.mjs,flowmcp-schemas/etherscan/getBalance.mjs"

`flowmcp group remove <name> --tools "refs"`

Remove tools from a group.

flowmcp group remove crypto --tools "flowmcp-schemas/coingecko/simplePrice.mjs"

`flowmcp group set-default <name>`

Set the default group used by call, test, and run commands.

flowmcp group set-default crypto

Validation & Testing (Dev Mode)

`flowmcp validate [path] [--group name]`

Validate schema structure against the FlowMCP specification.

flowmcp validate                          # Validate default group
flowmcp validate ./my-schema.mjs          # Validate single file
flowmcp validate --group crypto           # Validate specific group

`flowmcp test project [--route name] [--group name]`

Test default group schemas with live API calls.

flowmcp test project                          # Test all routes
flowmcp test project --route getBalance       # Test specific route
flowmcp test project --group crypto           # Test specific group

`flowmcp test user [--route name]`

Test all user-created schemas with live API calls.

flowmcp test user

`flowmcp test single <path> [--route name]`

Test a single schema file.

flowmcp test single ./my-schema.mjs
flowmcp test single ./my-schema.mjs --route getBalance

Execution

`flowmcp call list-tools [--group name]`

List available tools in the default or specified group.

flowmcp call list-tools
flowmcp call list-tools --group crypto

`flowmcp call <tool-name> [json] [--group name]`

Call a tool with optional JSON input.

flowmcp call coingecko_simplePrice '{"ids":"bitcoin","vs_currencies":"usd"}'
flowmcp call etherscan_getBalance '{"address":"0x..."}'  --group crypto

`flowmcp run [--group name]`

Start as an MCP server using stdio transport. This is used for integration with AI agent frameworks like Claude Code.

flowmcp run
flowmcp run --group crypto

Use flowmcp run to connect the CLI directly to Claude Desktop or other MCP-compatible AI clients via stdio transport.

Tool Reference Format

Tools are referenced using the source/file.mjs format:

source/file.mjs              # All tools from a schema
source/file.mjs::routeName   # Single tool from a schema

For example:

flowmcp-schemas/coingecko/simplePrice.mjs             # All routes
flowmcp-schemas/coingecko/simplePrice.mjs::getPrice   # Single route

Workflow Example

Initialize

Run the interactive setup. This imports schemas and creates a default group.

flowmcp init

Import schemas (optional)

If you skipped the import during init, add schemas manually:

flowmcp import https://github.com/FlowMCP/flowmcp-schemas

Create a group

Organize tools into a named group:

flowmcp group append crypto --tools "flowmcp-schemas/coingecko/simplePrice.mjs,flowmcp-schemas/etherscan/getBalance.mjs"
flowmcp group set-default crypto

Validate and test

Ensure schemas are correct and APIs respond:

flowmcp validate
flowmcp test project

Use tools

Call tools directly or start the MCP server:

flowmcp call list-tools
flowmcp call coingecko_simplePrice '{"ids":"bitcoin","vs_currencies":"usd"}'

# Or start as MCP server
flowmcp run

Environment Variables

API keys for schema testing go in ~/.flowmcp/.env:

ETHERSCAN_API_KEY=your_key_here
COINGECKO_API_KEY=your_key_here
DUNE_API_KEY=your_key_here

Never commit API keys to version control. The .env file in ~/.flowmcp/ is your global key store and should stay on your machine only.

Getting Started

Specification v2.0.0

Guides

Ecosystem

Reference

Installation

Architecture

Two Modes

Commands

`flowmcp init`

`flowmcp status`

`flowmcp mode [agent|dev]`

`flowmcp search <query>`

`flowmcp schemas`

`flowmcp add <tool-name>`

`flowmcp remove <tool-name>`

`flowmcp list`

`flowmcp import <url> [--branch name]`

`flowmcp import-registry <url>`

`flowmcp update [source-name]`

`flowmcp group list`

`flowmcp group append <name> --tools "refs"`

`flowmcp group remove <name> --tools "refs"`

`flowmcp group set-default <name>`

`flowmcp validate [path] [--group name]`

`flowmcp test project [--route name] [--group name]`

`flowmcp test user [--route name]`

`flowmcp test single <path> [--route name]`

`flowmcp call list-tools [--group name]`

`flowmcp call <tool-name> [json] [--group name]`

`flowmcp run [--group name]`

Tool Reference Format

Workflow Example

Environment Variables

Getting Started

Specification v2.0.0

Guides

Ecosystem

Reference

​Installation

​Architecture

​Two Modes

​Commands

​flowmcp init

​flowmcp status

​flowmcp mode [agent|dev]

​flowmcp search <query>

​flowmcp schemas

​flowmcp add <tool-name>

​flowmcp remove <tool-name>

​flowmcp list

​flowmcp import <url> [--branch name]

​flowmcp import-registry <url>

​flowmcp update [source-name]

​flowmcp group list

​flowmcp group append <name> --tools "refs"

​flowmcp group remove <name> --tools "refs"

​flowmcp group set-default <name>

​flowmcp validate [path] [--group name]

​flowmcp test project [--route name] [--group name]

​flowmcp test user [--route name]

​flowmcp test single <path> [--route name]

​flowmcp call list-tools [--group name]

​flowmcp call <tool-name> [json] [--group name]

​flowmcp run [--group name]

​Tool Reference Format

​Workflow Example

​Environment Variables

Installation

Architecture

Two Modes

Commands

`flowmcp init`

`flowmcp status`

`flowmcp mode [agent|dev]`

`flowmcp search <query>`

`flowmcp schemas`

`flowmcp add <tool-name>`

`flowmcp remove <tool-name>`

`flowmcp list`

`flowmcp import <url> [--branch name]`

`flowmcp import-registry <url>`

`flowmcp update [source-name]`

`flowmcp group list`

`flowmcp group append <name> --tools "refs"`

`flowmcp group remove <name> --tools "refs"`

`flowmcp group set-default <name>`

`flowmcp validate [path] [--group name]`

`flowmcp test project [--route name] [--group name]`

`flowmcp test user [--route name]`

`flowmcp test single <path> [--route name]`

`flowmcp call list-tools [--group name]`

`flowmcp call <tool-name> [json] [--group name]`

`flowmcp run [--group name]`

Tool Reference Format

Workflow Example

Environment Variables