> For the complete documentation index, see [llms.txt](https://docs.flowcp.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flowcp.ai/reference/cli.md). # FlowCP CLI The FlowCP CLI (`flowcp`) lets you manage your hosted MCP servers from the terminal or your IDE: connect apps, import OpenAPI documents, enable tools, publish servers, tail execution logs, configure auth, and sync skills, prompts, and widgets as local files. ## Installation Install from npm (Node.js 18 or newer): ```bash npm install -g flowcp flowcp --help ``` From a monorepo checkout (development builds): ```bash pnpm install pnpm --filter flowcp build node apps/cli/dist/bin.js --help ``` You can link a development build onto your PATH with `pnpm --filter flowcp link --global`. ## Logging in ```bash flowcp login ``` Login uses a browser device-code flow: the CLI prints a code and a dashboard URL (`/device`). Open the URL, sign in if needed, and approve the request — the CLI receives OAuth tokens scoped to your account and current workspace and stores them in `~/.flowcp/config.json` (file mode `0600`). No password ever passes through the terminal, and the CLI holds no client secret (it is a public OAuth client secured with PKCE). * `flowcp whoami` shows the logged-in user and workspace. * `flowcp workspace list` / `flowcp workspace switch ` change the active workspace. * `flowcp logout` removes stored credentials. The CLI talks to `https://api.flowcp.ai` by default. Point it at a different FlowCP instance (e.g. a local dev stack) with `--api-url ` or the `FLOWCP_API_URL` environment variable. ## Headless auth (CI / GitHub Actions) The device-code flow needs a browser, so it isn't usable on a CI runner. Instead, create a long-lived **API token** and pass it via an environment variable: ```bash flowcp token create --name "github-actions" ``` The full token is shown **once** — store it as a secret. Then, on any machine without `flowcp login`, set: | Variable | Purpose | | --------------------- | -------------------------------------------------------------- | | `FLOWCP_TOKEN` | An API token (`flowcp_pat_…`). Authenticates every command. | | `FLOWCP_API_URL` | API base URL (optional; defaults to `https://api.flowcp.ai`). | | `FLOWCP_WORKSPACE_ID` | Workspace id (optional; resolved from the token when omitted). | | `FLOWCP_CONFIG_DIR` | Override the config directory (default `~/.flowcp`). | ```bash export FLOWCP_TOKEN=flowcp_pat_xxxxxxxx flowcp whoami flowcp import run --app app_123 ``` Manage tokens with `flowcp token list` and `flowcp token revoke `. Tokens are stored hashed; revoke immediately stops a token from working. Tokens are scoped to the workspace and user that created them. See [Use FlowCP in GitHub Actions](/guides/github-actions.md) for a full workflow. ## The project file: `flowcp.json` Most commands need an app or server id. Instead of passing `--app` / `--server` every time, run `flowcp sync init --app --server ` in your project directory to create a `flowcp.json`: ```json { "appId": "app_...", "serverId": "srv_...", "workspaceId": "ws_...", "sync": { "skills": "Skills", "prompts": "Prompts", "widgets": "Widgets", "resources": "Resources", "docs": "Docs" } } ``` The CLI finds the nearest `flowcp.json` by walking up from the current directory. ## Command reference | Command | Description | | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | `flowcp login` / `logout` / `whoami` | Authenticate the CLI | | `flowcp token create --name ` / `list` / `revoke ` | Manage API tokens for headless / CI use | | `flowcp workspace list` / `switch ` | Manage the active workspace | | `flowcp app list` / `get [appId]` / `connect` | Manage connected apps | | `flowcp import run [--app ]` | Provision servers + import the OpenAPI doc (waits by default; `--no-watch` to queue only) | | `flowcp import folder [--server ] [--prune]` | Import a standard FlowCP folder's content into a server | | `flowcp import status [--watch]` | Check or watch an import | | `flowcp tools list` / `enable ` / `disable ` | Manage generated tools | | `flowcp server publish` / `unpublish` | Publish or unpublish a server | | `flowcp server config` | Print the MCP connection config (paste into an AI client) | | `flowcp server test` | Run the MCP capability test suite | | `flowcp export [--server ] [--out ]` | Export a published server as a self-hostable standard FlowCP folder (paid plans) | | `flowcp logs [--follow]` | Show (or tail) tool execution logs | | `flowcp invoke ""` | Run one playground chat turn against the server's tools | | `flowcp oauth get` / `set` | Manage the app's user-context OAuth provider config | | `flowcp auth-config list` / `set` / `delete ` | Manage shared-credential auth (api\_key / bearer / none) | | `flowcp domains list` / `add ` / `get ` / `remove ` | Manage custom domains | | `flowcp sync init` / `pull` / `push [--prune]` | Sync skills, prompts, widgets, resources, and docs as local files | Run `flowcp --help` for the full option list of any command. ## A typical flow ```bash flowcp login flowcp app connect --name "My API" --provider openapi \ --swagger-url https://api.example.com/openapi.json \ --api-base-url https://api.example.com # verify ownership in the dashboard, then: flowcp import run --app flowcp sync init --app --server flowcp tools list flowcp tools enable flowcp server publish flowcp server config flowcp logs --follow ``` ## Local sync for skills, prompts, widgets, resources, and docs `flowcp sync pull` downloads the server's skills, prompts, resources, and [documentation pages](/guides/serve-product-docs.md) as Markdown files with a frontmatter block, and widgets as an `.html` file plus a `.json` metadata sidecar, into the [standard FlowCP folder](/guides/folder-format.md) directories: ``` Skills/lookup_order.md Prompts/errors.md Widgets/order_card.html Widgets/order_card.json Resources/catalog.md Docs/overview.md Docs/guides/webhooks.md ``` `Docs/` is the one directory that nests: a page's file path below `Docs/` is its slug, so `Docs/guides/webhooks.md` syncs to the page served at `docs://guides/webhooks`. Edit them locally (with your IDE and version control), then `flowcp sync push` to upload changes. New files are created, changed files are updated, and `--prune` deletes server-side items that no longer have a local file. ## Exporting a self-hostable folder On a paid plan you can export a **published** server as a portable [standard FlowCP folder](/guides/folder-format.md) and run it on your own infrastructure with the FlowCP standalone runtime image — no FlowCP connection, Postgres, or Redis required: ```bash flowcp export --server --out ./my-server cd my-server cp .env.example .env # fill in FLOWCP_UPSTREAM_SECRET and any other values docker compose up ``` The folder is language-agnostic (`config.yaml` + per-item files + your OpenAPI document) and never contains secrets — you supply your upstream credential via the environment at run time. To import a folder's content into another server, use `flowcp import folder `. See [Export & self-host your MCP server](/guides/self-host-export.md). A skill file looks like: ```markdown --- description: 'Look up an order and summarize it' enabled: true --- # Lookup order 1. Call `get_order` with the order id... ``` ## Scripting with `--json` Every command accepts `--json` and prints the raw API payload, suitable for piping into `jq`: ```bash flowcp tools list --json | jq -r '.tools[] | select(.enabled) | .name' ``` Exit codes: `0` success, `1` generic error, `2` usage/validation error, `3` authentication required, `4` not found.