---
title: "proxymock CLI quickstart | Speedscale Docs"
description: "Record traffic, mock dependencies, and replay tests with the proxymock CLI using a demo Go app. Start locally, then choose CI/CD, Kubernetes, or cloud workflows."
canonical: "https://docs.speedscale.com/proxymock/getting-started/quickstart/quickstart-cli/"
---

[Documentation index](https://docs.speedscale.com/proxymock/llms.txt) | [Markdown](https://docs.speedscale.com/proxymock/getting-started/quickstart/quickstart-cli/index.md) | [Canonical page](https://docs.speedscale.com/proxymock/getting-started/quickstart/quickstart-cli/)

# proxymock CLI quickstart

Use the **proxymock CLI** to record a demo Go app, create a [mock server](https://docs.speedscale.com/reference/glossary/#mock-server), and replay the recording as tests. This walkthrough uses proxymock alone. For platform installation or an existing speedctl workflow, [choose a command-line tool](https://docs.speedscale.com/getting-started/command-line-tools/).

Security model

*   **Local-first:** proxymock keeps recorded traffic local by default.
*   **One-time activation:** proxymock runs locally, but you register a valid email once via `proxymock init` to activate it. It's free and your traffic stays on your machine.
*   **Optional cloud sync:** push snapshots only when you explicitly choose to.
*   **Enterprise controls:** if your org requires cloud boundary ownership, pair workflows with [BYOC](https://docs.speedscale.com/byoc/) and use [DLP](https://docs.speedscale.com/guides/dlp/) for sensitive fields.

<a id="choose-your-environment"></a>

## Choose Your Environment

Select your environment below and all instructions will update accordingly. If you prefer to run everything locally pick your operating system. If you want to access a pre-built environment in the cloud check out [GitHub Codespaces](https://github.com/speedscale/mock-lab).

**🍎 macOS**

You've selected **macOS**. All commands below are optimized for macOS systems.

**🐧 Linux**

You've selected **Linux**. All commands below are optimized for Linux systems.

**☁️ Codespaces**

![Codespaces](https://docs.speedscale.com/assets/images/codespaces-2ba682d739062e842fa91f01433e9e9e.png)

You've selected **GitHub Codespaces**. All commands below are optimized for the Codespaces environment with special notes for port forwarding and authentication.

<a id="setting-up-codespaces"></a>

### Setting up Codespaces

To get started with the mock-lab Codespace:

1.  Go to [github.com/speedscale/mock-lab](https://github.com/speedscale/mock-lab)
2.  Click the green **"Code"** button
3.  Select the **"Codespaces"** tab
4.  Click **"Create codespace on main"**
5.  Wait for the environment to initialize (usually 1-2 minutes)
6.  Once ready, you'll have a VS Code environment in your browser with all 7 runtimes and the proxymock CLI pre-installed

**🔧 Other**

You've selected **Other**. See our detailed installation guide for your specific system.

<a id="before-you-begin"></a>

## Before you begin

**🍎 macOS**

Make sure you have:

*   A terminal or command prompt open to run proxymock
*   A separate terminal or command prompt open to run the demo app
*   [git](https://git-scm.com/downloads) installed
*   [go version 1.23.1](https://go.dev/doc/install) or newer installed

**🐧 Linux**

Make sure you have:

*   A terminal or command prompt open to run proxymock
*   A separate terminal or command prompt open to run the demo app
*   [git](https://git-scm.com/downloads) installed
*   [go version 1.23.1](https://go.dev/doc/install) or newer installed

**☁️ Codespaces**

Make sure you have:

*   A GitHub account with access to Codespaces
*   The mock-lab Codespace running (note that go and proxymock are pre-installed)
*   Two terminal windows open in your Codespace

**🔧 Other**

Make sure you have:

*   A terminal or command prompt open to run proxymock
*   A separate terminal or command prompt open to run the demo app
*   [git](https://git-scm.com/downloads) installed
*   [go version 1.23.1](https://go.dev/doc/install) or newer installed

For this example we'll be using a simple demo app that accepts an API request, calls a downstream API and returns the results.

<a id="install"></a>

## Step 1: Install proxymock

Let your coding agent install it

Paste the prompt from [Install with your coding agent](https://docs.speedscale.com/proxymock/getting-started/installation/#install-with-ai-agent) into Claude Code, Cursor, Codex, or any agent that can run commands, then skip to Step 2. Prefer to install manually? Use the commands below.

**🍎 macOS**

Install with [Homebrew](https://brew.sh/):

```shell
brew install speedscale/tap/proxymock
```

**🐧 Linux**

Run the install script:

```shell
sh -c "$(curl -Lfs https://downloads.speedscale.com/proxymock/install-proxymock)"
```

**☁️ Codespaces**

No need to run any install scripts:

Codespaces Environment

proxymock is automatically available in the mock-lab Codespace.

**🔧 Other (Detailed)**

For other operating systems and more detailed instructions, see the [installation](https://docs.speedscale.com/proxymock/getting-started/installation/) instructions.

Need another OS like Windows or are you having issues? See advanced [installation](https://docs.speedscale.com/proxymock/getting-started/installation/).

<a id="api-key"></a>

## Step 2: Get and register your API key

If speedctl already uses the same account and tenant, [reuse that shared configuration](https://docs.speedscale.com/getting-started/command-line-tools/#credentials) and continue to [Step 3](https://docs.speedscale.com/proxymock/getting-started/quickstart/quickstart-cli/#recording). Otherwise initialize proxymock below.

**Easiest path:** Run `proxymock init` with no arguments and use the browser sign-in flow. Your configuration is saved automatically.

**If you already have a key or need a headless flow:** Get it from [sign up](https://app.speedscale.com/proxymock/signup) or, for enterprise customers, the [Profile page](https://app.speedscale.com/profile). Then register it:

![Where to find your API key](https://docs.speedscale.com/assets/images/api-key-b3a017301a096bcb9899b36b104c4c89.png)

```shell
proxymock init --api-key <your key>
```

For more detail (enterprise, CI, troubleshooting), see [Initialize API Key](https://docs.speedscale.com/proxymock/guides/initialize/).

If you want the language-specific landing pages after this Go-first quickstart, jump here:

*   [Java](https://docs.speedscale.com/reference/languages/java#proxymock) — Java demo app
*   [Kotlin](https://docs.speedscale.com/reference/languages/kotlin#proxymock) — Kotlin demo app
*   [.NET](https://docs.speedscale.com/reference/languages/dotnet#proxymock) — .NET demo app
*   [Node.js](https://docs.speedscale.com/reference/languages/nodejs#proxymock) — Node.js demo app
*   [Go](https://docs.speedscale.com/reference/languages/golang#proxymock) — Go demo app
*   [Python](https://docs.speedscale.com/reference/languages/python#proxymock) — Python demo app
*   [Ruby](https://docs.speedscale.com/reference/languages/ruby#proxymock) — Ruby demo app
*   [PHP](https://docs.speedscale.com/reference/languages/php#proxymock) — PHP demo app
*   [Rust](https://docs.speedscale.com/reference/languages/rust#proxymock) — Rust demo app
*   [C++](https://docs.speedscale.com/reference/languages/cpp#proxymock) — C++ demo app

<a id="recording"></a>

## Step 3: Install the demo app and start recording

**🍎 macOS**

```shell
git clone https://github.com/speedscale/mock-lab && cd mock-lab/languages/go && proxymock record -- go run .
```

**🐧 Linux**

```shell
git clone https://github.com/speedscale/mock-lab && cd mock-lab/languages/go && proxymock record -- go run .
```

**☁️ Codespaces**

If you're using the mock-lab Codespace, the repository is already cloned. Navigate to `languages/go` and start recording:

```shell
cd languages/go
export SSL_CERT_FILE="${HOME}/.speedscale/certs/tls.crt"
proxymock record -- go run .
```

**🔧 Other (Detailed)**

```shell
git clone https://github.com/speedscale/mock-lab && cd mock-lab/languages/go && proxymock record -- go run .
```

By running this you will start `proxymock` in recording mode while it runs the app as a child process. Now `proxymock` is listening on port 4143 for incoming traffic, which it forwards to the demo app running on port 8080. (proxymock also records outbound traffic on port 4140.) You'll see first the `proxymock` logs then a line across the screen, then the logs for the demo app. It should look something like this:

Output

```shell
$ proxymock record -- go run .
proxymock output will be redirected to proxymock/recorded-2025-07-30_15-19-11.417616Z/proxymock.log
Press ctrl-c to interrupt
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
2025/07/30 15:19:12 Starting HTTP server on :8080
```

<a id="run-tests"></a>

## Step 4: Run test transactions

Start a _new_ terminal and run the following command.

**🍎 macOS**

Run in new terminal window

```shell
# from the mock-lab repo root
./lab/tests/run_tests.sh --recording
```

**🐧 Linux**

Run in new terminal window

```shell
# from the mock-lab repo root
./lab/tests/run_tests.sh --recording
```

**☁️ Codespaces**

Run in new terminal window

```shell
# from the mock-lab repo root
./lab/tests/run_tests.sh --recording
```

Codespaces Port Forwarding

Make sure port 4143 is forwarded in your Codespace. You should see it automatically forwarded in the Ports tab.

**🔧 Other (Detailed)**

Run in new terminal window

```shell
# from the mock-lab repo root
./lab/tests/run_tests.sh --recording
```

You will now see a set of output from the tests:

Test output

```shell
$ ./lab/tests/run_tests.sh --recording
Recording mode enabled, using port 4143
Testing GET  http://localhost:4143/... OK (200)
Testing GET  http://localhost:4143/api/projects... OK (200)
Testing GET  http://localhost:4143/api/projects/kubernetes... OK (200)
Testing GET  http://localhost:4143/api/categories... OK (200)
Testing GET  http://localhost:4143/api/stats... OK (200)
Testing POST http://localhost:4143/oauth/token... OK (200)
Testing POST http://localhost:4143/api/orders... OK (201)
Testing GET  http://localhost:4143/api/orders/{order_id}... OK (200)
Http tests passed.
```

You can now press CTRL-C in the `proxymock record` terminal window to shut down recording.

You will also see some additional output in the original proxymock terminal window showing requests were handled by the demo app:

proxymock recording output

```shell
2025-07-30T15:31:57-04:00 INF Inbound latency=0.080292 method=GET path=/api/projects query=
2025-07-30T15:31:57-04:00 INF X-Header found header=Content-Type values=["application/json"]
2025-07-30T15:31:57-04:00 INF Outbound host=demo-api.trafficreplay.com latency=64.452875 method=GET status=200
...
```

<a id="view-recording"></a>

## Step 5: View recording results

There should be a new directory in the `proxymock` subdirectory inside `mock-lab/languages/go`. (An offline recording is also committed at `lab/proxymock/recording` if you'd rather skip recording and jump straight to mocking.)

```shell
ls proxymock
# Output shows recorded directories like:
# recorded-2025-07-30_15-31-43.701537Z
```

The traffic you just recorded is contained in the most recent directory. In this case that's `recorded-2025-07-30_15-31-43.701537Z` but it will change based on the date of recording. Each API request can be inspected as a markdown file:

```shell
$ cat proxymock/recorded-2025-07-30_15-31-43.701537Z/localhost/2025-07-30_19-56-08.410226Z.md

### REQUEST (TEST) ###
``
GET http://localhost:4143/ HTTP/1.1
Accept: */*
Host: localhost:4143
User-Agent: curl/8.7.1
...
```

<a id="run-mocks"></a>

## Step 6: Run mock server and tests

Go back to your original terminal (running `proxymock record`), stop proxymock by running CTRL-C and then start a mock server:

**🍎 macOS**

```shell
proxymock mock -- go run .
```

**🐧 Linux**

```shell
proxymock mock -- go run .
```

**☁️ Codespaces**

```shell
proxymock mock -- go run .
```

**🔧 Other (Detailed)**

```shell
proxymock mock -- go run .
```

Your demo app will now start using the local mock server.

note

When running `proxymock mock` your app no longer requires access to backend systems. The app will talk locally to proxymock instead of outside APIs.

Now exercise your demo app by running the same tests we ran before - except using the recording instead of a script. proxymock takes the recorded inbound requests and re-uses them as tests.

Open your second terminal window and run the following:

**🍎 macOS**

```shell
proxymock replay --test-against http://localhost:8080
```

**🐧 Linux**

```shell
proxymock replay --test-against http://localhost:8080
```

**☁️ Codespaces**

```shell
proxymock replay --test-against http://localhost:8080
```

**🔧 Other (Detailed)**

```shell
proxymock replay --test-against http://localhost:8080
```

The `proxymock replay` command will now run the original inbound transactions directly against your demo app. (You can also kick off a replay from the proxymock web UI.) The demo app no longer requires downstream systems for these tests as they are being simulated by proxymock. You should see a summary table like this:

```text
LATENCY / THROUGHPUT
+--------------------+--------+-------+-------+-------+-------+-------+-------+-------+------------+
|      ENDPOINT      | METHOD |  AVG  |  P50  |  P90  |  P95  |  P99  | COUNT |  PCT  | PER-SECOND |
+--------------------+--------+-------+-------+-------+-------+-------+-------+-------+------------+
| /                  | GET    |  1.00 |  1.00 |  1.00 |  1.00 |  1.00 |     2 | 20.0% |       9.93 |
| /api/projects      | GET    | 12.00 |  9.00 |  9.00 |  9.00 |  9.00 |     2 | 20.0% |       9.93 |
| /api/projects/{id} | GET    | 12.50 | 10.00 | 10.00 | 10.00 | 10.00 |     2 | 20.0% |       9.93 |
| /api/categories    | GET    | 14.00 | 13.00 | 13.00 | 13.00 | 13.00 |     2 | 20.0% |       9.93 |
| /api/stats         | GET    | 53.50 | 14.00 | 14.00 | 14.00 | 14.00 |     2 | 20.0% |       9.93 |
+--------------------+--------+-------+-------+-------+-------+-------+-------+-------+------------+
```

This demonstrates how you can test your microservice in isolation.

*   No need to write tests, you can replay the inbound traffic
*   No need to build a test environment, you can mock the dependencies
*   If you want to change the data, simply edit the markdown files

<a id="learn-more"></a>

## Learn More

Keep the [proxymock CLI reference](https://docs.speedscale.com/reference/proxymock-cli-reference/) handy for command flags. To take this recording beyond your machine, [choose a replay path](https://docs.speedscale.com/proxymock/guides/replay-paths/) or follow [proxymock in CI/CD](https://docs.speedscale.com/proxymock/guides/cicd/).

### ✏️ Editing Tests and Mocks

Learn how to [edit and customize](https://docs.speedscale.com/proxymock/guides/modify-rrpairs) your recorded tests and mocks to fit your specific testing needs.

[Edit Mocks](https://docs.speedscale.com/proxymock/guides/modify-rrpairs)

### 🔄 CI/CD Integration

Integrate proxymock into your [CI/CD pipeline](https://docs.speedscale.com/proxymock/guides/cicd/) to automate testing and ensure API reliability in your deployment process.

[Learn CI/CD](https://proxymock.io/blog/automating-api-mocks-in-your-ci-pipeline-with-proxymock/)

### 🌐 Remote Recorders

Deploy [remote recorders](https://docs.speedscale.com/quick-start) in your infrastructure to capture traffic from production environments and distributed systems.

[Install Recorders](https://docs.speedscale.com/quick-start)
