
Company News
Andrew Becherer Joins Socket as Chief Information Security Officer
Socket’s first CISO brings deep experience securing high-growth SaaS companies as open source supply chain threats accelerate.
callme-cli
Advanced tools
Professional command-line runner for API collections exported from the Callman desktop app. Runs requests, scripts, and contract checks via callman-core; emits HTML/JSON reports; CI-friendly exit codes.
Callme CLI is a professional command-line runner for API collections. It runs exported collections outside the desktop UI, loads exported environment variables, executes requests sequentially, runs scripts and contract checks through callman-core, prints terminal results, generates reports, and returns CI-friendly exit codes.
The CLI is intentionally thin: it handles file loading, orchestration, output, reports, and exit codes. Core execution logic stays inside callman-core.
Business users can use Callme CLI to prove that a business flow still works outside the desktop application, generate shareable HTML reports, and see a clear pass/fail summary.
QA engineers can run regression collections, validate response contracts, inspect failed script tests, and stop early with --bail when a flow is broken.
Developers can debug request execution with --verbose, inspect resolved headers/body/query values, verify environment mutations, and compare CLI behavior with the desktop app.
DevOps engineers can run collections in CI/CD pipelines, enforce exit codes, generate JSON/HTML artifacts, and use --no-fail when a pipeline stage should collect evidence without blocking deployment.
callman-core.pm.* test scripts through core.--no-fail, --bail, --verbose, --silent.callme_cli/
src/
index.ts CLI command registration and exit handling
execution.ts CLI orchestration loop around callman-core
loaders.ts Collection and environment file loading/normalization
format.ts Terminal output formatting
reports.ts JSON and HTML report generation
summary.ts Failure detection and summary helpers
types.ts CLI TypeScript types
data/
register-collection.json
environment.json
dist/ Compiled output
callman-core must be available. In this workspace it is linked locally with:"callman-core": "file:../callman_core"
From the callme_cli directory:
npm install
npm run build
Run locally without installing the global command:
npm run start -- run ./data/register-collection.json --env ./data/environment.json
After global linking, the command is:
callme run ./data/register-collection.json --env ./data/environment.json
If global linking fails with a permission error on macOS, use npm run start -- ... during development or configure npm to use a user-owned global prefix.
Callme CLI supports two run modes:
callme run <collection.json> --env <environment.json>
Reads JSON files exported from the desktop app off the local disk. Useful for ad-hoc local runs.
callme run \
--collection-id <collectionId> \
--environment-id <environmentId> \
--workspace <workspaceId> \
--token <cm_pat_...>
CLI fetches the collection + environment from the backend at runtime — no JSON files committed to your repo. The freshest version always runs.
Workspace + collection + environment IDs are visible in the desktop app:
Personal Access Tokens (PATs) are created in the desktop app: Workspace Settings → CI Tokens → New CI Token. The plain token is shown ONCE on creation — copy it immediately into your CI secret store. Tokens are workspace-scoped and revocable from the same UI.
Each value falls back through this chain (high → low):
| Value | CLI flag | Env var | Default |
|---|---|---|---|
| API URL | --api-url | CALLME_API_URL | https://api.callman.io |
| Token | --token | CALLME_TOKEN | (required) |
| Workspace ID | --workspace | CALLME_WORKSPACE_ID | (required) |
| Collection ID | --collection-id | none | (required) |
| Environment ID | --environment-id | none | (required) |
Default URL works — set 3 secrets (CALLME_TOKEN, CALLME_WORKSPACE_ID)
plus the two IDs as command args.
Point the CLI at your internal backend:
export CALLME_API_URL=https://api.callman.acme.local
export CALLME_TOKEN=cm_pat_...
export CALLME_WORKSPACE_ID=...
callme run \
--collection-id <collectionId> \
--environment-id <environmentId>
A PAT minted on one backend only works against that backend; cloud PATs do not authenticate against on-prem and vice versa.
# File mode
npm run start -- run <collection.json> --env <environment.json>
# Remote mode (against local backend)
npm run start -- run \
--api-url http://localhost:4000 \
--token <cm_pat_...> \
--workspace <workspaceId> \
--collection-id <collectionId> \
--environment-id <environmentId>
callme scenario run triggers a Callman scenario on the backend
worker and (by default) polls until it finishes. Unlike callme run,
the scenario does not execute locally — the worker has the DB / Kafka
/ Redis pools the scenario nodes need.
# Trigger + wait (default). Exit code reflects the run result.
callme scenario run \
--scenario-id <scenarioId> \
--environment-id <scenarioEnvId> \
--workspace <workspaceId> \
--token <cm_pat_...>
# Fire-and-forget — return as soon as the run is queued.
callme scenario run --scenario-id <id> --no-wait \
--workspace <id> --token <cm_pat_...>
# Save a JSON report when finished.
callme scenario run --scenario-id <id> \
--workspace <id> --token <cm_pat_...> \
--report json --output ./scenario.json
npm run start -- scenario run \
--api-url http://localhost:4000 \
--token cm_pat_J_acaYXOAxs1jSIMBL-R34p522QiHj5RQBJlXyQDcIQ \
--workspace 69ee34951f9f4d2754369276 \
--scenario-id 69f8f261f7f688ff34f50a79 \
--environment-id e76e66f1-3000-475c-a8d8-344886e7c829 \
--report json --output ./scenario-report.json \
--timeout 4000
Scenario triggers require the PAT to carry the pipeline:trigger
scope. Generate a new token from the desktop app (Workspace
Settings → CI Tokens → "New CI Token" → check Trigger). Tokens
created before this scope existed will get 403 with the message
Token is missing the 'pipeline:trigger' scope.
| Flag | Behaviour |
|---|---|
--scenario-id <id> | Required. Or set CALLME_SCENARIO_ID. |
--environment-id <id> | Optional. Names the scenario's inline environment to use (NOT a Mongo _id). Or set CALLME_SCENARIO_ENV_ID. Falls back to the first environment when omitted. |
--no-wait | Trigger and exit immediately with 0. The run keeps going server-side. |
--timeout <ms> | How long the CLI is willing to wait for a terminal state. Default: 1800000 (30 min). Hitting it exits 2 (fatal); the server-side run continues, it is not cancelled. |
--max-runtime <ms> | Advisory cap forwarded to the worker. |
--no-fail | Force exit 0 on failed / completed_with_failures / stopped. Overrides the priority gate. |
--fail-threshold <level> | Lowest scenario priority that flips the exit code on failure. Accepts critical, high, medium, low. Default: critical. See Scenario priority & pipeline gating below. |
--bail | Parsed but no-op for scenarios. Logged in non-silent mode. Kept for parity with callme run. |
--report json --output <file> | Dumps the slim report shape to disk. HTML reports are not yet supported for scenarios. |
Every scenario carries a priority (critical / high / medium
/ low), set in the desktop UI on the scenario itself. When a
scenario run fails, callme scenario run decides the exit code by
comparing that priority against --fail-threshold:
--fail-threshold critical → only critical scenario
failures break the pipeline (exit 1). high, medium, low
failures exit 0 and print a Pipeline not failed: notice so
reviewers know nothing was silently swallowed.--fail-threshold high → both critical and high failures
break the pipeline.--fail-threshold low → every failure breaks the pipeline (legacy
behaviour, all-or-nothing).--no-fail short-circuits the gate entirely — always exit 0.Pre-existing scenarios that never had a priority assigned report as
medium automatically (no migration required). The priority shown
in the report is snapshotted at trigger time, so changing the
scenario's priority after a run was triggered does not retroactively
change the report's exit code.
| State | --no-fail off (default) | --no-fail on |
|---|---|---|
success | 0 | 0 |
failed / completed_with_failures / stopped, priority ≥ --fail-threshold | 1 | 0 |
failed / completed_with_failures / stopped, priority < --fail-threshold | 0 (gated) | 0 |
| Timeout / network / auth error | 2 | 2 |
--no-wait trigger succeeded | 0 | 0 |
# Only critical scenarios break this stage (default).
callme scenario run --scenario-id <id> --token "$CALLME_TOKEN"
# Make any high-or-above failure break the pipeline.
callme scenario run --scenario-id <id> --fail-threshold high --token "$CALLME_TOKEN"
# Treat every failure as a pipeline break (legacy behaviour).
callme scenario run --scenario-id <id> --fail-threshold low --token "$CALLME_TOKEN"
# Collect evidence without ever breaking the pipeline.
callme scenario run --scenario-id <id> --no-fail --token "$CALLME_TOKEN"
A single --folder-id invocation runs every enabled scenario inside a
folder — useful when one pipeline stage is logically "all smoke tests
in the Auth area". Each scenario uses its own default environment
(environments[0]), so you don't need to pass --environment-id.
callme scenario run --folder-id <folderId> --token "$CALLME_TOKEN"
Two settings are configured on the folder in the desktop app (Sidebar → folder menu → Pipeline config):
sequential | parallel)
sequential (default) — scenarios run one at a time. Logs stay
ordered; the next scenario starts only after the previous
finishes.parallel — every scenario is triggered at once. Faster wall
clock, interleaved logs, higher backend load.Exit code semantics match single-scenario runs, but applied across the whole folder:
--fail-threshold
flips the folder run to exit 1.--no-fail still forces exit 0.--fail-threshold low makes any failure break the pipeline.The summary line at the end of a folder run reports N passed, M failed so CI logs always show the aggregate result before the
Exit code: line.
Restrictions in folder mode:
--scenario-id, --environment-id, --report, --output, and
--no-wait are rejected upfront — folder runs always poll all
scenarios and don't emit a per-folder report file.pipelineDisabledScenarioIds entry
no longer matches a real scenario.# Run every enabled scenario in the folder, default thresholds.
callme scenario run --folder-id <folderId> --token "$CALLME_TOKEN"
# Same, but break the pipeline on any failure regardless of priority.
callme scenario run --folder-id <folderId> --fail-threshold low \
--token "$CALLME_TOKEN"
callme run <collection> [options]
Arguments:
| Argument | Required | Meaning |
|---|---|---|
<collection> | Yes | Path to a collection JSON file. |
Options:
| Option | Value | Meaning |
|---|---|---|
--env <envFile> | File path | Loads environment variables from an exported environment JSON file. |
--report <json|html> | json or html | Generates a report in the selected format. |
--output <file> | File path | Output path for the report. Required when --report is used. |
--no-fail | Boolean | Always exits with code 0 after a completed run, even if requests, scripts, or contracts fail. Failures are still printed and included in reports. |
--bail | Boolean | Stops execution after the first failed request. Summary and reports include only executed requests. |
--verbose | Boolean | Prints detailed debug information for each executed request. |
--silent | Boolean | Prints only request status lines and summary. Overrides --verbose. |
The CLI accepts the exported collection shape used by the desktop app and normalizes it before passing requests to callman-core.
Minimum normalized shape:
{
"name": "Registration",
"requests": [
{
"id": "request-1",
"name": "Login",
"method": "POST",
"url": "https://api.example.com/login",
"headers": {
"Content-Type": "application/json"
},
"query": {
"source": "cli"
},
"body": {
"username": "{{env.username}}",
"password": "{{env.password}}"
},
"tests": "pm.test(\"status is 200\", () => { pm.response.to.have.status(200); });",
"contracts": [
{
"path": "data.token",
"rules": {
"required": true,
"type": "string",
"notEmpty": true
}
}
]
}
]
}
The CLI also understands desktop export fields such as:
collection.nameheaders as key/value arraysquery as key/value arraysauthtestsScriptpostResponseScriptcontractRulesExpected environment format:
{
"name": "staging",
"variables": {
"base_url": "https://api.example.com",
"AccessToken": "token-value"
}
}
Only variables are passed to callman-core.
For each request, the CLI:
callman-core to run the request.--bail is enabled and the request failed.A request is considered failed if any of these are true:
| Failure Type | Rule |
|---|---|
| Request failure | HTTP status is 0 or >= 400. Status 0 usually means network/request execution failure. |
| Script failure | Any script test result has status FAIL. |
| Contract failure | Any contract check result has status FAIL. |
This means a request can have HTTP 200 and still fail because a script test or contract check failed.
| Exit Code | Meaning | When It Happens |
|---|---|---|
0 | Success | All executed requests passed, or --no-fail was used. |
1 | Run failure | At least one executed request, script test, or contract check failed. |
2 | Fatal error | Invalid command, invalid file, invalid JSON, unsupported report type, missing report output, or unexpected runtime error. |
Normal run with failures:
callme run collection.json --env environment.json
# exits 1 if any request/script/contract fails
Collect failures but do not fail the process:
callme run collection.json --env environment.json --no-fail
# exits 0 even if failures exist
Stop early but do not fail the process:
callme run collection.json --env environment.json --bail --no-fail
# stops on first failure, exits 0
Normal mode prints:
Example:
Running collection: Registration
[1/8] POST /api/v3/registration/pin .... 200 OK (316ms)
Script Tests:
PASS Status code is 200
Contract Checks:
PASS Contract: data.last_sms
Summary:
Requests: 8
Passed: 7
Failed: 1
Silent mode prints only:
It hides:
Command:
callme run collection.json --env environment.json --silent
Example:
[1/8] POST /api/v3/registration/pin .... 200 OK (316ms)
[2/8] POST /api/v2/login .... 200 OK (89ms)
Summary:
Requests: 8
Passed: 7
Failed: 1
Verbose mode prints normal output plus:
Command:
callme run collection.json --env environment.json --verbose
Verbose output is useful for developers and QA when comparing CLI behavior with desktop execution.
Important: verbose output may print secrets such as tokens, API keys, cookies, and personal data. Avoid using --verbose in shared CI logs unless logs are protected.
--no-failUse --no-fail when you want the CLI to complete and produce evidence without failing the shell process.
Behavior:
0 unless a fatal error occursTypical use cases:
Example:
callme run collection.json --env environment.json --no-fail
--bailUse --bail when later requests depend on earlier successful requests.
Behavior:
1 if a failure occurred, unless --no-fail is usedTypical use cases:
Example:
callme run collection.json --env environment.json --bail
--verboseUse --verbose for debugging.
Behavior:
Example:
callme run collection.json --env environment.json --verbose
--silentUse --silent for compact CI logs.
Behavior:
--verboseExample:
callme run collection.json --env environment.json --silent
| Combination | Result |
|---|---|
--silent --verbose | Silent wins. Verbose logs are hidden. |
--bail --no-fail | Execution stops early, but final exit code is 0. |
--report ... --silent | Report is still written, but the report path message is hidden. |
--report without --output | Fatal error, exit code 2. |
--output without --report | Fatal error, exit code 2. |
The following table describes all combinations of the four execution flags.
| Flags | Execution | Output | Exit Code On Run Failure |
|---|---|---|---|
| none | Runs all requests | Normal | 1 |
--no-fail | Runs all requests | Normal | 0 |
--bail | Stops after first failure | Normal | 1 |
--verbose | Runs all requests | Detailed debug | 1 |
--silent | Runs all requests | Minimal | 1 |
--no-fail --bail | Stops after first failure | Normal | 0 |
--no-fail --verbose | Runs all requests | Detailed debug | 0 |
--no-fail --silent | Runs all requests | Minimal | 0 |
--bail --verbose | Stops after first failure | Detailed debug | 1 |
--bail --silent | Stops after first failure | Minimal | 1 |
--verbose --silent | Runs all requests | Minimal because silent wins | 1 |
--no-fail --bail --verbose | Stops after first failure | Detailed debug | 0 |
--no-fail --bail --silent | Stops after first failure | Minimal | 0 |
--no-fail --verbose --silent | Runs all requests | Minimal because silent wins | 0 |
--bail --verbose --silent | Stops after first failure | Minimal because silent wins | 1 |
--no-fail --bail --verbose --silent | Stops after first failure | Minimal because silent wins | 0 |
Callme CLI supports JSON and HTML reports.
Command:
callme run collection.json --env environment.json --report json --output report.json
Output shape:
{
"collectionName": "Registration",
"summary": {
"total": 8,
"passed": 7,
"failed": 1
},
"results": []
}
Use JSON reports for:
Command:
callme run collection.json --env environment.json --report html --output report.html
The HTML report includes:
Use HTML reports for:
Generate a JSON report and fail CI on failures:
callme run collection.json --env environment.json --report json --output report.json
Generate an HTML report and fail CI on failures:
callme run collection.json --env environment.json --report html --output report.html
Generate a report but never fail the process:
callme run collection.json --env environment.json --report html --output report.html --no-fail
Stop early and write a report for executed requests:
callme run collection.json --env environment.json --report html --output report.html --bail
Stop early, write a report, but exit 0:
callme run collection.json --env environment.json --report html --output report.html --bail --no-fail
Write a report with minimal terminal logs:
callme run collection.json --env environment.json --report json --output report.json --silent
Debug and write an HTML report:
callme run collection.json --env environment.json --report html --output report.html --verbose
Run a flow and generate a readable report:
callme run registration.json --env staging.json --report html --output registration-report.html
Meaning:
Run regression tests and stop at the first broken step:
callme run regression.json --env qa.json --bail --report html --output regression.html
Meaning:
Debug variable resolution, request body, response body, and env changes:
callme run collection.json --env local.json --verbose
Meaning:
Run in CI and fail the pipeline on test or contract failures:
callme run collection.json --env ci.json --silent --report json --output callme-report.json
Meaning:
Run a collection, collect the report, but do not block the pipeline:
callme run collection.json --env ci.json --silent --no-fail --report html --output callme-report.html
Meaning:
0name: API Regression
on:
pull_request:
workflow_dispatch:
jobs:
api-regression:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- name: Install CLI
working-directory: callme_cli
run: npm ci
- name: Build CLI
working-directory: callme_cli
run: npm run build
- name: Run API collection
working-directory: callme_cli
run: npm run start -- run ./data/register-collection.json --env ./data/environment.json --silent --report json --output report.json
- name: Upload report
uses: actions/upload-artifact@v4
if: always()
with:
name: callme-report
path: callme_cli/report.json
- name: Run non-blocking API health check
working-directory: callme_cli
run: npm run start -- run ./data/register-collection.json --env ./data/environment.json --silent --no-fail --report html --output report.html
callme run collection.json --env ci.json --silent --bail --report json --output report.json
Meaning:
1 on failureBuild:
npm run build
Run with sample data:
npm run start -- run ./data/register-collection.json --env ./data/environment.json
Run and generate HTML:
npm run start -- run ./data/register-collection.json --env ./data/environment.json --report html --output report.html
Run and generate JSON:
npm run start -- run ./data/register-collection.json --env ./data/environment.json --report json --output report.json
Run silently:
npm run start -- run ./data/register-collection.json --env ./data/environment.json --silent
Run verbose:
npm run start -- run ./data/register-collection.json --env ./data/environment.json --verbose
Run fail-fast:
npm run start -- run ./data/register-collection.json --env ./data/environment.json --bail
Run without failing the shell:
npm run start -- run ./data/register-collection.json --env ./data/environment.json --no-fail
zsh: command not found: callmeThe global callme command is not linked or installed.
Use the local development command:
npm run start -- run ./data/register-collection.json --env ./data/environment.json
Or link the CLI globally after building:
npm run build
npm link
npm linkIf npm tries to write into /usr/local/lib/node_modules and fails with EACCES, your global npm prefix is not writable by your user.
Recommended options:
npm run start -- ... during developmentAvoid changing system permissions unless you understand the impact.
Fatal: Collection.name must be a non-empty stringThe collection file does not have a supported collection name.
Supported examples:
{
"name": "Registration",
"requests": []
}
or:
{
"collection": {
"name": "Registration"
},
"requests": []
}
Unsupported report typeOnly these report types are supported:
jsonhtmlCorrect:
callme run collection.json --report html --output report.html
Incorrect:
callme run collection.json --report hml --output report.html
--report Requires --outputThis is invalid:
callme run collection.json --report html
Use:
callme run collection.json --report html --output report.html
--output Requires --reportThis is invalid:
callme run collection.json --output report.html
Use:
callme run collection.json --report html --output report.html
A request can fail even when HTTP status is 200.
That happens when:
Example:
GET /userinfo .... 200 OK
Contract Checks:
FAIL pin length expected at least 8, got 7
The CLI treats this as a failed request because the API contract is not satisfied.
Environment files may contain tokens, API keys, passwords, customer data, or other secrets.
Be careful with:
--verbose, because it prints headers, request body, response body, and environment changesRecommended practices:
--silent in public logsCallme CLI is split from callman-core.
callman-core owns:
Callme CLI owns:
This separation keeps the core reusable by CLI, desktop, frontend, and future automation tools.
For local debugging:
npm run start -- run ./data/register-collection.json --env ./data/environment.json --verbose
For QA regression:
npm run start -- run ./data/register-collection.json --env ./data/environment.json --bail --report html --output report.html
For CI gating:
npm run start -- run ./data/register-collection.json --env ./data/environment.json --silent --report json --output report.json
For non-blocking CI evidence:
npm run start -- run ./data/register-collection.json --env ./data/environment.json --silent --no-fail --report html --output report.html
npm run start -- scenario run --api-url http://localhost:4000 --token cm_pat_6G6Eic2bc3PO6ET3zU6_BYtCAL5j7hJfHWrHkTRYFVo --workspace 6a00d92f0288bc493f4cf846 --folder-id 6a14726b680ab39a0b921fa0
FAQs
Professional command-line runner for API collections exported from the Callman desktop app. Runs requests, scripts, and contract checks via callman-core; emits HTML/JSON reports; CI-friendly exit codes.
The npm package callme-cli receives a total of 83 weekly downloads. As such, callme-cli popularity was classified as not popular.
We found that callme-cli demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Company News
Socket’s first CISO brings deep experience securing high-growth SaaS companies as open source supply chain threats accelerate.

Company News
Replit is integrating Socket Firewall into its AI-powered development experience to help protect builders from malicious open source packages.

Security News
npm confirmed a tooling bug incorrectly marked several one-character packages as security holders and said it was working on a rollback.