CLI Reference (OSS Proxy)

Which product has a CLI

This CLI is the host binary for the OSS proxy, not the licensed product. The two are operated very differently:

Synopsis

Running the binary with no subcommand is equivalent to gostly start with all defaults — this preserves the container-entrypoint behaviour. Every other subcommand is a short-lived HTTP client that connects to a proxy already running on localhost.

gostly [COMMAND] [OPTIONS]

Commands:
  start     Start the proxy (default if no subcommand is given)
  mode      Set proxy mode (LEARN, MOCK, PASSTHROUGH)
  status    Show proxy health
  stop      Gracefully stop a locally running proxy
  export    Export the recorded mock library in the named format
  import    Import an OpenAPI / Postman / WireMock spec into the mock library
  logs      Tail proxy logs from the data dir

Run `gostly <command> --help` for command-specific options.

gostly --version prints the version, commit, and build flavour, e.g. gostly v0.1.0 (commit 7688c16, oss). The subcommand client commands default to port 8080, override per-command with --port or the GOSTLY_CLI_PORT environment variable.

gostly start

Starts the proxy daemon. This is the only subcommand that runs the long-lived process; the others are clients that talk to it. Command-line flags win over environment variables — supplied flags are pushed back into the process environment that the daemon reads, with the data-dir guard leaving any already-set container env (e.g. a compose-provided traffic directory) in place.

gostly start [OPTIONS]

Options:
  --upstream <URL>        Upstream URL the proxy forwards to (env: BACKEND_URL)
  --port <PORT>           Port the proxy listens on (default: 8080)
  --data-dir <DIR>        Data dir for mocks, statechart overrides, and the
                          pidfile (default: ./data)
  --mode <MODE>           Initial mode: learn | mock | passthrough
                          (default: learn)

The proxy listens for plain HTTP on the configured port (default 8080). TLS interception (the :8443 MITM listener) is governed by the ENABLE_TLS_INTERCEPTION environment variable, not a CLI flag — see TLS Interception.

# Start in LEARN mode, recording traffic for an upstream
gostly start --upstream http://localhost:3000 --mode learn

gostly mode

Sets the proxy's operating mode on a running proxy. The agent has four modes total — LEARN, MOCK, PASSTHROUGH, and TRANSITIONING — but the CLI sets only the three steady-state modes. TRANSITIONING is a brief interstitial the proxy enters itself during a LEARN→MOCK transition (returning 503 with a Retry-After header); it is not a value you set directly.

gostly mode <MODE> [OPTIONS]

Arguments:
  <MODE>           learn | mock | passthrough

Options:
  --port <PORT>    Proxy port (default: 8080, env: GOSTLY_CLI_PORT)

The command issues a request to the proxy's control endpoint and prints the mode it set.

gostly mode mock
# mode set to MOCK (...)

gostly status

Queries the proxy's health endpoint and prints the JSON response. Use it to confirm the proxy is up and to read back the current mode and process state.

gostly status [OPTIONS]

Options:
  --port <PORT>    Proxy port (default: 8080, env: GOSTLY_CLI_PORT)

gostly stop

Gracefully stops a locally running proxy by sending it a SIGTERM. It reads the PID from the pidfile first; if the pidfile is absent it falls back to locating the process by name. The command returns success even when no proxy is running, so it is safe in teardown scripts.

gostly stop [OPTIONS]

Options:
  --pidfile <PATH>    Path to the pidfile (default: data/gostly.pid)

gostly export

Reads the recorded mock library from the running proxy and prints it to stdout, tagged with the requested format. The format values are openapi (default), postman, and har.

gostly export [OPTIONS]

Options:
  --format <FORMAT>    openapi | postman | har (default: openapi)
  --port <PORT>        Proxy port (default: 8080, env: GOSTLY_CLI_PORT)

gostly export --format openapi > mocks.json

gostly import

Imports an OpenAPI, Postman, or WireMock specification into the mock library. Unlike the other client subcommands, import does not talk to the proxy — it calls the control-plane API, so that side must be reachable (default http://127.0.0.1:8000).

gostly import <FILE> [OPTIONS]

Arguments:
  <FILE>                  Path to the spec file (.json / .yaml / .zip)

Options:
  -f, --format <FORMAT>   openapi | postman | wiremock
  -s, --service-id <ID>   ServiceUpstream id to bind the imported mocks to
  --api-url <URL>         Control-plane base URL
                          (default: http://127.0.0.1:8000, env: API_URL)
  --api-key <KEY>         API key for the control plane (env: GHOST_API_KEY)

Each format posts to the matching control-plane import route — /mocks/import/openapi, /mocks/import/postman, or /mocks/import/wiremock. The supported import formats (openapi, postman, wiremock) differ from the export formats above.

gostly import collection.json \
  --format postman \
  --service-id payments \
  --api-url http://127.0.0.1:8000

gostly logs

Tails the proxy log file from the data dir. The proxy writes structured logs to stdout/stderr; logs reads <data-dir>/proxy.logif you have redirected the proxy's output there. With --follow it streams new lines as they arrive.

gostly logs [OPTIONS]

Options:
  --follow            Follow new log lines (tail -f)
  --data-dir <DIR>    Data dir holding the log file (default: ./data)

If no log file exists at <data-dir>/proxy.log, the command tells you how to redirect the proxy's output into one.

# Capture proxy output, then follow it
gostly start ... 2>&1 | tee ./data/proxy.log &
gostly logs --follow

Observing the proxy

Beyond the CLI, the proxy exposes Prometheus metrics at /metrics. The primary match-path signal is the match_type label on ghost_requests_total; the mock-library size is ghost_mock_library_size, disk-sink failures are ghost_io_errors_total{operation}, HTTP rate and latency come from axum_http_requests_total / axum_http_requests_duration_seconds, and the TLS subsystem emits the gostly_tls_* family.