CLI

The Echopoint CLI manages flows and collections from the terminal and runs flows ephemerally in CI. It also provides MCP tools for AI clients. Its source is public on GitHub at github.com/nanostack-dev/echopoint-cli.

Install

macOS and Linux — checksum-verified, installs to ~/.local/bin, no sudo:

curl -fsSL https://raw.githubusercontent.com/nanostack-dev/echopoint-cli/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/nanostack-dev/echopoint-cli/main/install.ps1 | iex

Prebuilt binaries are also published on GitHub Releases. Once installed, the CLI updates itself:

echopoint update    # self-update to the latest release
echopoint version   # print the installed version

Authentication

Common authentication options:

Method	How	Use for
Browser login	`echopoint auth login` (OAuth via Clerk)	Local development
Token flag	Global `--token <token>` on a command	A supplied session token
Token env var	`ECHOPOINT_TOKEN`	Scripted sessions
API key pair	`ECHOPOINT_API_KEY` + `ECHOPOINT_ORGANIZATION_ID`	CI pipelines

# CI: no login step needed — the CLI picks up the env pair directly
export ECHOPOINT_API_KEY=<key>
export ECHOPOINT_ORGANIZATION_ID=<org id>
echopoint auth status

Create CI keys with the ci preset — see API keys & permissions.

Configuration and profiles

Settings live in ~/.echopoint/config.yaml; credentials are stored separately per profile. Profiles point the CLI at alternate API URLs and switch between them:

echopoint profile add staging --api-url https://api.echopoint.dev
echopoint profile use staging
echopoint profile list

Every command supports table, JSON, or YAML output:

echopoint flows list -o json

Command tour

This guide targets CLI v2.0.2. The canonical resource names are flow and collection; flows and collections remain supported aliases. view is the current inspection command, with get and flow show retained as aliases. Interactive flow creation was removed in v2, and there is no dedicated flow export command. Create a flow from a definition file and use flow view -o json to inspect it. Local Specs document commands were also removed; the current spec commands work with workspace specs. Run echopoint spec --help for that separate command group.

Group	Commands	Purpose
`auth`	`login` `logout` `status`	Sign in and inspect the active session
`flow`	`list` `view` `create` `update` `delete` `launch` `run` `validate`	Manage and execute flows
`flows node`	`add` `update` `remove`	Edit nodes — types `request`, `delay`, `module`, `webhook_wait`
`flows node output`	`add` `remove`	CLI output extractors (json_path, status_code, header, body)
`flows node assertion`	`add` `remove`	Assertions on node responses
`flows edge`	`add` `remove`	Connect nodes with `--type success\|failure`
`flows env`	`get` `set` `unset` `delete`	Flow-level environment variables
`flows tag`	`--add` / `--remove`, `--query`, `--match-tag`, `--match-mode any\|all`	Tag flows and search by tag
`flows execution`	`get` `list`	Inspect run history and execution metadata
`collections`	`list` `get` `create` `update` `delete` `import`	Manage collections; `import --file` takes an OpenAPI spec
`org env`	`get` `set` `unset` `delete`, `-e <name>`, `environments list\|delete`	Org defaults and named overlays
`profile` / `config`	—	Profiles and local configuration
`version` / `update`	—	Version info and self-update

Frequently used examples:

echopoint flows validate <flow-id>
echopoint flow view <flow-id> -o json
echopoint flows tag --add smoke <flow-id>
echopoint flows execution list <flow-id>
echopoint collections import --file openapi.yaml
echopoint org env set -e staging --var BASE_URL=https://staging.example.com

flows run: ephemeral CI execution

echopoint flows run launches an ephemeral execution and claims its one-shot job. The claim delivers the flow and resolved inputs to the CLI, which runs its embedded engine locally. It reports progress, heartbeats, and completion with a per-job token. The API key needs flows:execute; add flows:read for tag selection.

The worker receives referenced environment secrets so it can make requests. Use a trusted worker and a dedicated key. The CLI does not log those resolved inputs.

# Run specific flows by ID
echopoint flows run <flow-id> <another-flow-id>

# Run a tag suite against staging, three flows at a time
echopoint flows run --tag smoke --environment staging --parallel 3

# Pin a published version and dedupe retried pipelines
echopoint flows run <flow-id> --version-id <version-id> --idempotency-key "$CI_RUN_ID"

Flag	Behavior
`--tag`	Select flows by tag; repeatable; `--match-mode any\|all`; cap 50 flows
`--environment <key>`	Resolve org/flow variables for that environment
`--version-id`	Run a pinned published version
`--parallel N`	Run up to N flows concurrently
`--poll-timeout`	Max wait for completion (default 30m)
`--idempotency-key`	Deduplicate launches across pipeline retries
`-o json`	Machine-readable results
`--verbose`	Live node-by-node status while running

Exit codes gate pipelines directly: 0 all flows passed, 1 a flow failed, 2 cancelled, 3 contract or API error, 4 timeout.

Use with an AI agent

Echopoint works with your own agent in two ways. Both require access to an Echopoint workspace and authentication; the hosted app is accepting waitlist requests. Your agent owns its reasoning and code changes. Echopoint supplies test operations and execution results.

MCP-compatible clients

Install the CLI and authenticate with echopoint auth login. Configure your MCP client to launch the CLI as a local stdio server:

{
  "mcpServers": {
    "echopoint": {
      "command": "echopoint",
      "args": ["mcp"]
    }
  }
}

The configuration format can vary by client. The executable must be on the client’s PATH; see the CLI MCP setup guide for details. Calls use your credentials and permissions. Connect a test workspace and review your client’s tool approvals before allowing it to write or execute.

The build_flow tool can create a flow with request or module steps, outputs, assertions, and edges. Inspect existing flows and choose a unique name: build_flow replaces an existing flow with the same name. An agent can call launch_flow, then inspect the execution with get_execution and get_execution_node_results. Launching is asynchronous; a launch response alone is not a passing test. Private targets still need a runner with access to their network.

Agents with terminal access

A terminal-capable agent can use the same CLI as a developer. Once you have a flow and a staging environment, replace the placeholders with real IDs:

echopoint flows validate <flow-id>
echopoint flows run <flow-id> --environment staging -o json

The JSON output includes an execution ID, node results, and assertions with expected, actual, and passed fields. Inspect failures before changing your app or tests, then rerun to check the result. Use test data and a test environment: executing a flow sends real requests and may create or delete records according to the flow definition.

echopoint flows execution get <flow-id> <execution-id> -o json reads the stored execution metadata; it is not the detailed node assertion report. Use MCP get_execution_node_results for stored per-node results.

For authoring, use echopoint flows create --file flow.json or the node, output, assertion, and edge commands. The flow guide and assertion reference explain the model. Reuse the resulting flow in the GitHub Action once it checks the behavior you intend.

Next steps

GitHub Action — the same run as a one-step workflow
API keys & permissions — scopes a CI key needs
Tags & search — build tag-based suites
Runners — cloud, self-hosted, and ephemeral execution