Command line interface

hcc is a multi-purpose command line interface for Hoverfly Cloud. It provides a convenient way to manage your Hoverfly Cloud virtual services and automate their management. Either for ad-hoc actions via the command line or integrated into scripts that are used by Continuous Integration and DevOps tools such as Jenkins.

You can capture traffic within your network and publish the simulation to your account with hcc.

See the Reference page for a full list of commands.



Download the correct version using the links above. Unpack the zip file and you are good to go.

You may copy the unpacked binary to /usr/local/bin (for Mac and Linux), so that you can run hcc without specifying the full path.

Verifying the installation by running

hcc version

It should print out the version, such as v2.0.0

Getting started

After you download and install the CLI, create an API token on the Account page.

Run the following command to configure hcc to authenticate with your account:

hcc config set api-token {your API token}

The API token is stored in ~/.hcc/config.yaml for future use.

Start a service

Launch a virtual service from the command line:

  • Using a local simulation file.

hcc service start my-service --simulation-file FILE_NAME
  • Or using a simulation created on Hoverfly Cloud.

hcc service start my-service --simulation-name SIMULATION_NAME

Update the simulation

Update the simulation data on a service:

  • Using a local simulation file.

hcc service update my-service --simulation-file FILE_NAME
  • Or using a simulation created on Hoverfly Cloud.

hcc service update my-service --simulation-name SIMULATION_NAME

Reset a service

You can wipe the simulation data, journal and states by reseting the service:

hcc service reset my-service

Delete a service

Delete a service from the command line:

hcc service delete my-service

If your service contains simulation data that is not saved, it will be lost. You may want to export the simulation first.

Start a capture service

Launch a Hoverfly Cloud service to capture a remote API from the command line:

hcc service start my-service --mode capture --target-url

You should pass the base URL of the API to the --target-url flag.

Update the proxy mode

If you have started a service with proxy enabled by setting the --target-url and --mode . You can switch the mode using the following command:

hcc service update my-service --mode spy

See here for a list of available proxy modes.

Export a simulation

Export the simulation data from a service to a new simulation resource on your Hoverfly Cloud account:

hcc service export my-service --simulation-name SIMULATION_NAME

Your service must be running, and the SIMULATION_NAME must not conflict with an existing name.