Echolot
Command line and CI

Command-line tool

Install the echolot command, and learn what every command shares: secrets, environment variables and exit codes.

echolot runs what you build in the app from a terminal or a CI job: it sends requests, runs a workspace with its checks and writes reports, imports and exports collections, lints specs, serves mocks, runs flows and serves a workspace to AI agents over MCP. It reads the same workspace files as the app, so nothing needs converting.

Get the command-line tool

The direct download carries the tool inside the app. To put it on your PATH:

  1. Choose Echolot › Install Command-Line Tool…, or open Settings › General and click Install Command-Line Tool… under Command-line tool.
  2. Echolot puts an echolot link to the tool inside the app in /opt/homebrew/bin or /usr/local/bin. Where neither folder is writable, macOS asks for an administrator's password.
  3. Open a new Terminal window and type echolot --help.

Settings › General › Command-line tool shows where the bundled tool is and the link on your PATH. Use Reinstall after you move the app, and Remove to take the link away. If a file named echolot that Echolot did not put there is in the way, Echolot asks before it replaces it, and the file goes to the Trash.

Because the link points into the app, the tool updates with the app.

Mac App Store edition

The App Store edition has no tool inside it and no Install Command-Line Tool… item. Install the tool from the zip on the releases page instead. It works with the same workspaces.

Compare the editions

The command-line tool never expires, also in beta builds of the app. It needs macOS 15 or later on a Mac.

Commands

CommandWhat it does
echolot sendSends one request, a URL or a saved request file, and writes the body to standard output.
echolot runRuns a workspace, some of its folders or requests, or a Postman collection, with checks and reports.
echolot validateChecks that every file of a workspace reads and every request resolves.
echolot import, echolot exportBrings collections into a workspace and writes a workspace out as Postman, Insomnia, Bruno or Echolot.
echolot mcpChecks MCP servers, signs in to them, serves a workspace to agents and prints client setups.
echolot specLints OpenAPI documents, and checks and applies spec changes to the folder that follows the spec.
echolot graphql diffCompares two GraphQL schemas and grades every change.
echolot grpcDescribes gRPC services and calls their methods.
echolot mqttSubscribes at and publishes to MQTT brokers.
echolot mockServes a mock: a workspace mock's routes, or an OpenAPI document.
echolot fakeMakes fake data from a template, for fixtures and seed data.
echolot flowLists, runs, creates and serves a workspace's flows.
echolot agentRuns the built-in agent on a task, with a policy instead of approvals.

echolot help <command> and echolot <command> --help print every option of a command. Commands with subcommands take them the same way: echolot mcp serve --help.

Options every command has

OptionMeaning
--versionPrints the version and build, such as 0.5.0 (8).
-h, --helpPrints the command's options.

Workspaces and environments

Commands that work on a workspace take its folder, the one with workspace.toml in it. Some take it as an argument (echolot run Alpenglow.echolot), others with -w or --workspace (echolot flow list -w Alpenglow.echolot); each command's page says which. Where it is optional, the current folder is used.

--env chooses an environment by its file name without .toml (staging). run, validate and flow also take its name (Staging). Without --env, requests resolve with the workspace's own variables. See environments.

Secrets

Secret values never live in workspace files: a file names the secret variable and nothing more. The command-line tool finds each value in this order:

  1. An environment variable ECHOLOT_SECRET_<NAME>. The name is the variable's name in capitals, with every character that isn't a letter or a digit turned into _: token is ECHOLOT_SECRET_TOKEN, me_password is ECHOLOT_SECRET_ME_PASSWORD.
  2. For echolot run, a file given with --secrets: one NAME=value per line, # for comments, quotes around a value are taken off. NAME is the variable's name (token=…) or the whole environment variable name (ECHOLOT_SECRET_TOKEN=…). Values in the file win over environment variables.
  3. On a Mac, the Keychain items the app keeps. A secret you set in the app, or an MCP server you signed in to, works in Terminal too.
export ECHOLOT_SECRET_PASSWORD="$(op read 'op://Shop/Alpenglow staging/password')"
echolot run Alpenglow.echolot --env staging

The Keychain is never used when CI is set (to anything but empty, 0 or false), or when ECHOLOT_KEYCHAIN=0. That keeps a CI job from waiting on a Keychain prompt. See secrets.

Environment variables

VariableUsed byMeaning
ECHOLOT_SECRET_<NAME>Every command that resolves requestsThe value of the secret variable <NAME>.
ECHOLOT_KEYCHAIN=0Every commandDon't read or write the Keychain.
CIEvery commandWhen set, the Keychain is off, as with ECHOLOT_KEYCHAIN=0.
HTTPS_PROXY, HTTP_PROXY, ALL_PROXY, NO_PROXYsend, run, mqtt and othersProxies, read as curl reads them. --proxy and --no-proxy override them; a workspace's own proxy setting comes first.
ECHOLOT_CERT_PASSPHRASEsend, run, mqttThe passphrase of the key or PKCS#12 file given with --cert or --key.
ECHOLOT_MQTT_PASSWORDmqttThe broker password.
ECHOLOT_MCP_TOKENmcp serve --httpThe bearer token clients send; a random one otherwise.
ECHOLOT_WEBHOOK_TOKENflow serveThe token webhook callers send; a random one otherwise.
ECHOLOT_BROWSERmcp sign-inThe command that opens the sign-in page instead of the default browser.
ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEYagentThe model provider's API key.
NO_COLORrunPlain console output.

Output and exit codes

Results go to standard output: a response body, a report, the lines a subscription prints. Progress, warnings, test results and timings go to standard error, so you can pipe the output on:

echolot send https://demo.echolot.dev/v1/products/TNT-MH-2P | jq .name
Exit codeMeaning
0Everything worked and every check passed.
1Something failed: no response, a failing check or test, problems found (validate, spec lint), breaking changes (graphql diff), a gRPC status other than OK, a refused MQTT connection, an agent that didn't finish.
22echolot send only: the response's status was 400 or more, as with curl --fail.
64The command line itself was wrong: an unknown option, a missing file, an environment that doesn't exist. The reason is printed.

Next

Settings

Every pane of Echolot's Settings, each option in it, what it does and its default.

echolot send

Send one request from the terminal, a URL or a saved request, and read its body, headers, timing and wire bytes.

On this page

Get the command-line toolCommandsOptions every command hasWorkspaces and environmentsSecretsEnvironment variablesOutput and exit codesNext