Running Mocko

CLI

The CLI is how Mocko runs on your machine: one command that serves your mocks, watches your files, and hosts the control panel. This page covers every option, from ports to proxying to Redis mode.

Install

The CLI requires Node.js 20.19 or newer and is installed globally from npm:

$npm install -g @mocko/cli

On an older Node version the CLI refuses to start and points you to the update instructions, so there is no way to end up on a broken install silently.

Everyday usage

Point the CLI at a folder of .hcl files, usually with watch mode on so edits apply immediately:

$mocko --watch mocks

Mocks are served on http://localhost:8080 and the control panel on http://localhost:6625. Both the folder and the flags are optional: a bare mocko starts an empty instance you can drive entirely from the UI, which is how the quickstart runs it.

Ports

-p moves the mock server, -P moves the UI:

$mocko -p 4000 -P 4625 --watch mocks

A common reason to move the mock port: running Mocko in place of the service your frontend already points at, so no client configuration changes at all.

Proxying to a real backend

-u sets the proxy target for requests no mock matches, turning Mocko into a selective layer in front of a real API:

$mocko -u https://demo-api.mockoapp.net --watch mocks

Proxied requests time out after 30 seconds by default; -t changes that in milliseconds. The mock-side behavior of proxying is covered in Proxying and Hosts.

Running without the UI

The control panel is on by default. --no-ui turns it off, which fits CI jobs and scripted environments where nobody will open a browser:

$mocko --no-ui --watch mocks

Redis mode

By default the CLI runs storeless: mocks created in the UI, hosts, and flags all live in memory and reset when the process stops. -r connects Mocko to a Redis instance and makes that state durable:

$mocko -r redis://localhost:6379 --watch mocks

Storeless is a feature for local work: every session starts clean. Reach for Redis when state should survive restarts or be shared. The full breakdown of what lives where is on Persistence and Redis.

All options

Usage: mocko [options] [path to mocks folder]
Example: mocko -p 4000 mocks

  -h, --help       Shows this screen
  -v, --version    Shows the current version
  -w, --watch      Watches for file changes and restarts the server
  -p, --port       Port to serve the mocks (8080)
  -u, --url        URL to proxy requests when no mock is defined
  -t, --timeout    Max time to wait for a proxied response in millis (30000)
  --no-ui          Disables the control panel UI
  -r, --redis      Enables Redis mode using the provided Redis URL
  -P, --ui-port    Overrides the UI port (default: 6625)

Behavior details

The CLI wires the control panel to the mock server automatically, generating a fresh internal secret on every run. There is nothing to configure or protect on localhost.
Without a mocks folder argument, file mocks are simply disabled for that session; the CLI prints a note so it is never a surprise.

To run Mocko alongside the rest of your local stack instead of as a global CLI, continue to Docker Compose.

CLI