← Docs

CLI Reference

Manage your entire Testfly workflow from the terminal. Create workspaces, upload specs, configure mock auth, and test endpoints.

Installation

The Testfly CLI is distributed as a .NET global tool. Requires .NET 10 SDK or later.

terminal

$ dotnet tool install -g Testfly.Cli

Verify the installation:

terminal

$ testfly --version
testfly 1.0.0
                

Configuration

Initialize a config file in your project directory:

terminal

$ testfly init
[OK] Created testfly.json

$ testfly init --url https://api.custom-testfly.com

This creates a testfly.json file:

testfly.json

{
  "apiUrl": "https://api.testfly.com",
  "apiKey": null,
  "token": null,
  "defaultWorkspaceId": null
}
                

The CLI looks for config in this order:

./testfly.json in the current directory
~/.testfly/config.json as a global fallback

Authentication

Two authentication methods are supported. API keys are recommended for most workflows.

API Key (recommended)

terminal

$ testfly auth set-key tf_live_your_api_key_here
[OK] API key saved.
                

Email / Password

terminal

$ testfly login --email you@company.com --password yourpassword
[OK] Logged in successfully.
[INFO] Authenticated as you@company.com
                

API key auth sends an X-API-Key header. Login auth stores a JWT token and sends it as a Bearer token.

Workspaces

List workspaces

terminal

$ testfly workspace list

ID          NAME        SLUG        STATUS  ROWS
--------    --------    --------    ------  ----
7f8e3a1b..  Petstore    petstore    Active  100
a2c4e6g8..  Payments    payments    Active  500
                

Create a workspace

terminal

$ testfly workspace create --name "Petstore" --slug petstore --rows 100 --seed 42
[OK] Workspace created: 7f8e3a1b-...
                

Set a default workspace

Avoid typing the workspace ID on every command:

terminal

$ testfly workspace use 7f8e3a1b-4c5d-6e7f-8a9b-0c1d2e3f4a5b
[OK] Default workspace set to 7f8e3a1b-...
                

Other workspace commands

Command	Description
`workspace get [id]`	Get workspace details (uses default if no ID)
`workspace update <id> [options]`	Update name, rows, latency, error rate, auth type
`workspace delete <id>`	Delete a workspace and all its data
`workspace regenerate [id]`	Regenerate all mock data from scratch
`workspace pause [id]`	Pause a workspace (stops serving requests)
`workspace resume [id]`	Resume a paused workspace

Specs

Upload a spec

terminal

$ testfly spec upload --file openapi.yaml --version v2
[OK] Spec uploaded: d9f1b2c3-...
                

If you have a default workspace set, the workspace ID is optional. Otherwise, pass it as the first argument:

terminal

$ testfly spec upload 7f8e3a1b-... --file openapi.yaml

List and inspect specs

terminal

$ testfly spec list

ID          VERSION  TITLE       STATUS     ACTIVE
--------    -------  --------    --------   ------
d9f1b2c3..  v2       Petstore    Processed  yes
c3b2a1f9..  v1       Petstore    Processed  no

$ testfly spec resources 7f8e3a1b-... d9f1b2c3-...
$ testfly spec routes 7f8e3a1b-... d9f1b2c3-...
                

Mock Requests

Send HTTP requests directly to your mock endpoints:

terminal

# GET request
$ testfly mock petstore GET /pets
HTTP 200  GET /mock/petstore/pets
{ "data": [...], "meta": { "totalCount": 100 } }

# POST with JSON body
$ testfly mock petstore POST /pets --body '{"name": "Rex", "species": "dog"}'
HTTP 201  POST /mock/petstore/pets

# With custom headers
$ testfly mock petstore GET /pets --header 'Authorization: Bearer test123'

# Using default workspace slug
$ testfly mock GET /pets
                

The mock command uses the workspace slug (not the ID). If you have a default workspace set, the CLI resolves its slug automatically.

Mock Auth

Configure your mock workspace to require authentication headers. This doesn't validate credentials — it only checks that the header is present with a non-empty value. Useful for testing that your client application sends auth headers correctly.

Bearer Token Auth

Requires an Authorization: Bearer <token> header on every request:

terminal

$ testfly workspace update <id> --auth-type bearer

# Requests without auth get 401
$ testfly mock petstore GET /pets
HTTP 401  GET /mock/petstore/pets
{ "error": "Unauthorized — provide auth header" }

# Include the header
$ testfly mock petstore GET /pets --header 'Authorization: Bearer any-token-here'
HTTP 200  GET /mock/petstore/pets
                

API Key Auth

Requires a custom header (default: X-API-Key) on every request:

terminal

$ testfly workspace update <id> --auth-type apikey

# Custom header name
$ testfly workspace update <id> --auth-type apikey --auth-key-name "X-Custom-Key"

# Include the header
$ testfly mock petstore GET /pets --header 'X-API-Key: any-value'
HTTP 200  GET /mock/petstore/pets
                

Disable Auth

terminal

$ testfly workspace update <id> --auth-type none

Presence-only validation

Mock auth does not validate token values or API keys. Any non-empty value is accepted. This is intentional — it lets you test that your client sends the correct headers without needing real credentials.

Ready to get started?

Install the CLI and create your first mock workspace in under a minute.

$ dotnet tool install -g Testfly.Cli

Getting Started Guide API Reference