What Is the Hoppscotch CLI?

Hoppscotch is an open-source API ecosystem: web app, desktop app, CLI, and self-hostable backend. It is often described as an open alternative to Postman and Insomnia. The Hoppscotch CLI lets you run Hoppscotch collections from a terminal, which makes it useful for CI/CD API testing.

Try Apidog today

This guide shows how to install the Hoppscotch CLI, run collections with hopp test, pass environments and CSV data, generate JUnit reports, and wire everything into GitHub Actions. If you are comparing runners, see the best Hoppscotch CLI alternatives and the direct Apidog CLI vs Hoppscotch CLI comparison.

What the Hoppscotch CLI does

The Hoppscotch CLI is published as the npm package @hoppscotch/cli.

Its job is focused:

1. Load a Hoppscotch collection.
2. Run each request in that collection.
3. Execute pre-request and test scripts.
4. Evaluate assertions.
5. Exit with a success or failure code that CI can read.

Think of it as a collection runner, similar to Newman for Postman or inso for Insomnia.

It does not design APIs, mock endpoints, or generate documentation. It runs requests and checks assertions.

That narrow scope is useful if you already maintain Hoppscotch collections and want a lightweight way to run them in CI.

Because Hoppscotch is open source, you can also self-host the stack and point the CLI at your own Hoppscotch instance. The trade-off is operational: you own the hosting.

Install the Hoppscotch CLI

Install the CLI globally from npm:

npm i -g @hoppscotch/cli

Check your installed versions:

node --version
hopp --version

Current Hoppscotch CLI releases require Node.js v22 or newer.

If your local machine or CI runner uses Node 20, either:

• upgrade the runtime to Node 22+, or
• stay on Hoppscotch CLI v0.26.0.

For CI, pin the Node version explicitly. Otherwise, your pipeline may fail during install or runtime before your API tests even start.

Run a collection with hopp test

The main command is hopp test.

Run a local collection file:

hopp test ./my-collection.json

Run the collection with an environment file:

hopp test ./my-collection.json -e ./staging.env.json

Add a delay between requests:

hopp test ./my-collection.json -e ./staging.env.json -d 500

Useful flags:

Flag	Alias	Purpose
--env	-e	Provide an environment file
--delay	-d	Wait between requests in milliseconds

Use --delay when your target API is rate-limited or when requests depend on backend state that needs a short time to settle.

Run a collection from Hoppscotch Cloud or a self-hosted instance

If your collection is stored in Hoppscotch instead of a local JSON file, run it by collection ID.

For a self-hosted Hoppscotch server:

hopp test <collection-id> \
  --token <access_token> \
  --server https://hoppscotch.your-company.com

For Hoppscotch Cloud, omit --server:

hopp test <collection-id> --token <access_token>

Use:

• --token for your personal access token.
• --server for your self-hosted Hoppscotch URL.

In CI, store the token as a secret instead of hardcoding it in your workflow file.

Run data-driven API tests

For data-driven runs, pass a CSV file:

hopp test ./my-collection.json \
  --iteration-data ./users.csv \
  --iteration-count 3

--iteration-data points to a CSV file. Each column becomes a variable available during the run.

Example users.csv:

email,password
[e-mail],password1
[e-mail],password2
[e-mail],password3

--iteration-count controls how many times the collection runs.

This is useful for cases like:

• testing login with multiple users,
• validating role-based API access,
• running the same workflow against multiple records,
• checking different request payloads from fixture data.

Generate JUnit reports

The Hoppscotch CLI can write JUnit XML:

hopp test ./my-collection.json --reporter-junit ./report.xml

Most CI systems can ingest JUnit XML and show test results in the build UI.

Example output path:

./report.xml

JUnit XML is the structured report format supported by the CLI. If you need built-in HTML reports, JSON reports, or hosted report links, compare that with tools like the Apidog CLI.

What runs during hopp test

For each request in the collection, the CLI runs the request lifecycle in order:

1. Execute the pre-request script.
2. Send the HTTP request.
3. Execute the test script.
4. Evaluate assertions.

Hoppscotch test scripts use the scripting API.

Example test:

pw.test("Status is 200", () => {
  pw.expect(pw.response.status).toBe(200);
});

If the assertion passes, the test passes.

If any assertion fails, hopp test exits with a non-zero code.

That exit-code behavior is what makes it CI-friendly:

• exit 0 means the API test run passed,
• non-zero exit means the build should fail.

GitHub Actions example

Here is a minimal GitHub Actions workflow that runs Hoppscotch API tests on every push:

name: API tests

on: [push]

jobs:
  hopp:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - run: npm i -g @hoppscotch/cli

      - run: hopp test ./collection.json -e ./ci.env.json --reporter-junit ./report.xml

The important part is this step:

- uses: actions/setup-node@v4
  with:
    node-version: 22

Without it, your runner may use an older Node.js version that is incompatible with the current Hoppscotch CLI.

If you want to publish the JUnit report as an artifact, add:

      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: hopp-junit-report
          path: ./report.xml

Example with a self-hosted Hoppscotch collection in CI

If your collection is stored in a self-hosted Hoppscotch instance, use secrets for the token:

name: API tests

on: [push]

jobs:
  hopp:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - run: npm i -g @hoppscotch/cli

      - name: Run Hoppscotch collection
        run: |
          hopp test ${{ secrets.HOPP_COLLECTION_ID }} \
            --token ${{ secrets.HOPP_TOKEN }} \
            --server https://hoppscotch.your-company.com \
            --reporter-junit ./report.xml

Store these values in your repository or organization secrets:

• HOPP_COLLECTION_ID
• HOPP_TOKEN

Limitations to keep in mind

The Hoppscotch CLI is useful, but it has a focused scope.

Key limitations:

• It is a collection runner, not a full API platform. It does not handle API design, mocking, or documentation.
• You manage collection access. The CLI runs local files or pulls collections from a Hoppscotch instance.
• JUnit is the main structured report output. There is no built-in HTML report.
• Node.js v22+ is required for current releases. Pin the runtime in CI.

These limits are not necessarily problems. They are the trade-off of using a small, open-source CLI focused on running API collections.

If your workflow expands into API design, mocking, richer reports, and managing API resources as code, an integrated platform may fit better. Apidog covers the full API lifecycle, and the Apidog CLI complete guide explains the CLI workflow. You can also download Apidog, import a Hoppscotch collection, and compare directly, or follow the migration walkthrough.

FAQ

Is the Hoppscotch CLI free?

Yes. It is open source under the Hoppscotch project, and you can self-host the ecosystem. See the official CLI docs and the GitHub repo.

What is the difference between hopp test and Newman?

Both are collection runners with data-driven iterations.

The difference is the collection format:

• Newman runs Postman collections.
• hopp test runs Hoppscotch collections.

The core CI concepts are similar: run requests, evaluate assertions, use CSV data when needed, and fail the build with a non-zero exit code.

Can the Hoppscotch CLI run collections from a self-hosted server?

Yes.

Use:

hopp test <collection-id> \
  --token <access_token> \
  --server <your-url>

This pulls and runs a collection from your own Hoppscotch instance.

Does it produce HTML reports?

Not directly.

The CLI writes JUnit XML with:

hopp test ./my-collection.json --reporter-junit ./report.xml

For CLI, HTML, and JSON reports together, compare with Apidog CLI test reports.

Bottom line

The Hoppscotch CLI is a clean way to run Hoppscotch API collections in CI.

Use it when you need to:

• run collections from the terminal,
• execute request-level test scripts,
• fail builds on assertion failures,
• generate JUnit XML for CI results.

For stable CI runs, pin Node.js v22, keep tokens in secrets, and publish the JUnit output from every build.