Qampanion CLI Reference

A command-line tool to work with Qampanion projects. You can get information about devices, test cases, and test plans, and also run tests on a device.

You can access the tool at the following path:

/Applications/Qampanion.app/Contents/MacOS/QampanionCLI

create-project

Create a new Qampanion project at the specified path.

Parameter	Required	Description
--path	Yes	Path to the directory where the project will be created.
--name	Yes	Name of the new project.
--json	No	Print the result as JSON.

Example:

QampanionCLI create-project --path "/path/to/projects" --name "MyProject"
QampanionCLI create-project --path "/path/to/projects" --name "MyProject" --json

get-devices

Get a list of devices that are available to run tests on.

Parameter	Required	Description
--os	No	Filter devices by OS. Use ios or android.
--json	No	Print the result as JSON.

Example:

QampanionCLI get-devices
QampanionCLI get-devices --os ios
QampanionCLI get-devices --os android --json

get-test-cases

Get a list of test cases from a Qampanion project file.

Parameter	Required	Description
--project	Yes	Path to the .qpn project file.
--json	No	Print the result as JSON.

Example:

QampanionCLI get-test-cases --project "/path/to/Project.qpn"
QampanionCLI get-test-cases --project "/path/to/Project.qpn" --json

get-test-case

Get detailed information about a specific test case, including its steps and actions.

ℹ️ Step snapshots (reference images) are excluded from the output.

Parameter	Required	Description
--project	Yes	Path to the .qpn project file.
--test	Yes	Test case ID. Use get-test-cases to find it.
--json	No	Print the result as JSON.

Example:

QampanionCLI get-test-case \
  --project "/path/to/Project.qpn" \
  --test "A1B2C3D4-0000-0000-0000-000000000000"

QampanionCLI get-test-case \
  --project "/path/to/Project.qpn" \
  --test "A1B2C3D4-0000-0000-0000-000000000000" \
  --json

get-test-result

Get the saved test result log for a specific test case. The result is written after running the test case via run-test-case or run-test-plan.

Parameter	Required	Description
--test	Yes	Test case ID. Use get-test-cases to find it.
--json	No	Print the result as JSON.

Example:

QampanionCLI get-test-result --test "A1B2C3D4-0000-0000-0000-000000000000"
QampanionCLI get-test-result --test "A1B2C3D4-0000-0000-0000-000000000000" --json

get-test-plans

Get a list of test plans from a Qampanion project file.

Parameter	Required	Description
--project	Yes	Path to the .qpn project file.
--json	No	Print the result as JSON.

Example:

QampanionCLI get-test-plans --project "/path/to/Project.qpn"
QampanionCLI get-test-plans --project "/path/to/Project.qpn" --json

get-ui-hierarchy

Get the current UI element tree from a running device. Returns all visible elements with their coordinates, types, and labels. Coordinates are returned in device pixel space (scaled by the device's scale factor) and can be used directly with perform-action.

Parameter	Required	Description
--device	Yes	Device ID. Use get-devices to find it.
--json	No	Print the result as JSON.

Example:

QampanionCLI get-ui-hierarchy \
  --device "0EBECE94-2084-4F51-8591-9A82A8C3B549"

QampanionCLI get-ui-hierarchy \
  --device "0EBECE94-2084-4F51-8591-9A82A8C3B549" \
  --json

Plain-text output format:

<type> | <name> | <elementDescription> | x:<x> y:<y> w:<width> h:<height>

JSON output format:

[
  {
    "id": "A1B2C3D4-0000-0000-0000-000000000000",
    "x": 207.0,
    "y": 375.5,
    "width": 225.0,
    "height": 61.0,
    "type": "StaticText",
    "name": "Test Card",
    "elementDescription": "text"
  }
]

create-test-case

Create a new test case in a Qampanion project file.

Parameter	Required	Description
--project	Yes	Path to the .qpn project file.
--name	Yes	Name of the new test case.
--description	No	Description of the new test case.
--json	No	Print the result as JSON.

Example:

QampanionCLI create-test-case \
  --project "/path/to/Project.qpn" \
  --name "Login flow"

QampanionCLI create-test-case \
  --project "/path/to/Project.qpn" \
  --name "Login flow" \
  --description "Verifies login screen" \
  --json

create-step

Create a new step in an existing test case.

Parameter	Required	Description
--project	Yes	Path to the .qpn project file.
--test-case-id	Yes	Test case ID. Use get-test-cases to find it.
--description	Yes	Description of the new step.
--threshold	No	Snapshot comparison threshold in percent (default: the test case setting).
--json	No	Print the result as JSON.

Example:

QampanionCLI create-step \
  --project "/path/to/Project.qpn" \
  --test-case-id "A1B2C3D4-0000-0000-0000-000000000000" \
  --description "Tap login button"

QampanionCLI create-step \
  --project "/path/to/Project.qpn" \
  --test-case-id "A1B2C3D4-0000-0000-0000-000000000000" \
  --description "Tap login button" \
  --threshold 90 \
  --json

update-step

Update the description, name, or snapshot threshold of an existing step. Use it when a step was created with wrong values. Only the passed fields are changed. --description and --threshold work for default steps and can be combined. --name works only for linked steps and cannot be combined with other fields.

Parameter	Required	Description
--project	Yes	Path to the .qpn project file.
--test-case-id	Yes	Test case ID.
--step-id	Yes	Step ID. Use get-test-case --json to find it.
--description	No*	New description of the step. Not for linked steps.
--name	No*	New name of the linked step. Only for linked steps.
--threshold	No*	New snapshot comparison threshold in percent. Only for default steps.
--json	No	Print the result as JSON.

Example:

QampanionCLI update-step \
  --project "/path/to/Project.qpn" \
  --test-case-id "A1B2C3D4-0000-0000-0000-000000000000" \
  --step-id "B2C3D4E5-0000-0000-0000-000000000000" \
  --description "Login Screen — verify the login form is shown"

QampanionCLI update-step \
  --project "/path/to/Project.qpn" \
  --test-case-id "A1B2C3D4-0000-0000-0000-000000000000" \
  --step-id "B2C3D4E5-0000-0000-0000-000000000000" \
  --threshold 90

delete-step

Delete a step from a test case by ID. The step is removed with all its actions and zones.

Parameter	Required	Description
--project	Yes	Path to the .qpn project file.
--test-case-id	Yes	Test case ID.
--step-id	Yes	Step ID to delete.

Example:

QampanionCLI delete-step \
  --project "/path/to/Project.qpn" \
  --test-case-id "A1B2C3D4-0000-0000-0000-000000000000" \
  --step-id "B2C3D4E5-0000-0000-0000-000000000000"

create-action

Create a new action in an existing step.

Parameter	Required	Description
--project	Yes	Path to the .qpn project file.
--test-case-id	Yes	Test case ID. Use get-test-cases to find it.
--step-id	Yes	Step ID. Use get-test-case --json to find it.
--description	Yes	Description of the new action.
--type	Yes	Action type: tap, swipe, type, wait.
--x	No	X coordinate for tap action (default: 0).
--y	No	Y coordinate for tap action (default: 0).
--from-x	No	Start X coordinate for swipe action (default: 0).
--from-y	No	Start Y coordinate for swipe action (default: 0).
--to-x	No	End X coordinate for swipe action (default: 0).
--to-y	No	End Y coordinate for swipe action (default: 0).
--text	No	Text to input for type action (default: empty string).
--seconds	No	Duration in seconds for wait action (default: 0).
--json	No	Print the result as JSON.

Example:

# tap
QampanionCLI create-action \
  --project "/path/to/Project.qpn" \
  --test-case-id "A1B2C3D4-0000-0000-0000-000000000000" \
  --step-id "B2C3D4E5-0000-0000-0000-000000000000" \
  --description "Tap on submit" \
  --type tap \
  --x 540 --y 1200

# swipe
QampanionCLI create-action \
  --project "/path/to/Project.qpn" \
  --test-case-id "A1B2C3D4-0000-0000-0000-000000000000" \
  --step-id "B2C3D4E5-0000-0000-0000-000000000000" \
  --description "Swipe up" \
  --type swipe \
  --from-x 500 --from-y 1500 --to-x 500 --to-y 500

# type
QampanionCLI create-action \
  --project "/path/to/Project.qpn" \
  --test-case-id "A1B2C3D4-0000-0000-0000-000000000000" \
  --step-id "B2C3D4E5-0000-0000-0000-000000000000" \
  --description "Enter username" \
  --type type \
  --text "user@example.com"

# wait
QampanionCLI create-action \
  --project "/path/to/Project.qpn" \
  --test-case-id "A1B2C3D4-0000-0000-0000-000000000000" \
  --step-id "B2C3D4E5-0000-0000-0000-000000000000" \
  --description "Wait for animation" \
  --type wait \
  --seconds 3

update-action

Update an existing action in a step. Use it when an action was created with wrong values. Only the passed fields are changed. The --type can also be changed — pass the fields for the new type together with it. Pass at least one field.

Parameter	Required	Description
--project	Yes	Path to the .qpn project file.
--test-case-id	Yes	Test case ID.
--step-id	Yes	Step ID. Use get-test-case --json to find it.
--action-id	Yes	Action ID to update.
--description	No*	New description of the action.
--type	No*	New action type: tap, swipe, type, wait.
--x, --y	No*	Coordinates for tap action.
--from-x, --from-y, --to-x, --to-y	No*	Coordinates for swipe action.
--text	No*	Text for type action.
--seconds	No*	Duration for wait action.
--json	No	Print the result as JSON.

Example:

# Fix the tap coordinates
QampanionCLI update-action \
  --project "/path/to/Project.qpn" \
  --test-case-id "A1B2C3D4-0000-0000-0000-000000000000" \
  --step-id "B2C3D4E5-0000-0000-0000-000000000000" \
  --action-id "C3D4E5F6-0000-0000-0000-000000000000" \
  --x 540 --y 1250

# Change the action type to wait
QampanionCLI update-action \
  --project "/path/to/Project.qpn" \
  --test-case-id "A1B2C3D4-0000-0000-0000-000000000000" \
  --step-id "B2C3D4E5-0000-0000-0000-000000000000" \
  --action-id "C3D4E5F6-0000-0000-0000-000000000000" \
  --type wait \
  --seconds 3

delete-action

Delete an action from a step by ID.

Parameter	Required	Description
--project	Yes	Path to the .qpn project file.
--test-case-id	Yes	Test case ID.
--step-id	Yes	Step ID. Use get-test-case --json to find it.
--action-id	Yes	Action ID to delete.

Example:

QampanionCLI delete-action \
  --project "/path/to/Project.qpn" \
  --test-case-id "A1B2C3D4-0000-0000-0000-000000000000" \
  --step-id "B2C3D4E5-0000-0000-0000-000000000000" \
  --action-id "C3D4E5F6-0000-0000-0000-000000000000"

create-linked-step

Create a new linked step in an existing test case. A linked step references another test case, allowing you to reuse existing test logic.

Parameter	Required	Description
--project	Yes	Path to the .qpn project file.
--test-case-id	Yes	Test case ID to add the linked step to. Use get-test-cases to find it.
--name	Yes	Name of the linked step.
--linked-test-case-id	Yes	Test case ID that this step links to.
--required	No	Whether the step is required (default: true). Pass --no-required to make it optional.
--json	No	Print the result as JSON.

Example:

QampanionCLI create-linked-step \
  --project "/path/to/Project.qpn" \
  --test-case-id "A1B2C3D4-0000-0000-0000-000000000000" \
  --name "Re-use login flow" \
  --linked-test-case-id "B2C3D4E5-0000-0000-0000-000000000000"

QampanionCLI create-linked-step \
  --project "/path/to/Project.qpn" \
  --test-case-id "A1B2C3D4-0000-0000-0000-000000000000" \
  --name "Optional onboarding" \
  --linked-test-case-id "B2C3D4E5-0000-0000-0000-000000000000" \
  --no-required \
  --json

create-network-request-step

Create a new network request step in an existing test case.

Parameter	Required	Description
--project	Yes	Path to the .qpn project file.
--test-case-id	Yes	Test case ID. Use get-test-cases to find it.
--description	Yes	Description of the new step.
--url	Yes	Target URL for the request.
--method	Yes	HTTP method: get, post, put, delete, patch.
--expected-status-code	No	Expected HTTP status code (default: 200).
--headers	No	Request headers as a JSON string (default: empty).
--body	No	Request body as a JSON string (default: empty).
--json	No	Print the result as JSON.

Example:

QampanionCLI create-network-request-step \
  --project "/path/to/Project.qpn" \
  --test-case-id "A1B2C3D4-0000-0000-0000-000000000000" \
  --description "Login API call" \
  --url "https://api.example.com/login" \
  --method post \
  --expected-status-code 200 \
  --headers '{"Content-Type": "application/json"}' \
  --body '{"username": "test", "password": "123"}' \
  --json

create-comparison-parameter

Create a new response comparison parameter in an existing network request step.

Parameter	Required	Description
--project	Yes	Path to the .qpn project file.
--test-case-id	Yes	Test case ID. Use get-test-cases to find it.
--step-id	Yes	Network request step ID. Use get-test-case --json to find it.
--description	Yes	Human-readable description of the parameter.
--key	Yes	Response key to validate. Supports dot-notation (e.g. user.id) and bracket-notation (e.g. items[0].name).
--comparison-type	Yes	Comparison type: without (no validation), equal (exact match), exists (key presence).
--expected-value	No	Expected value. Required when --comparison-type is equal.
--environment-key	No	Environment key to save the response value to after execution.
--json	No	Print the result as JSON.

Example:

# Check status field equals "active"
QampanionCLI create-comparison-parameter \
  --project "/path/to/Project.qpn" \
  --test-case-id "A1B2C3D4-0000-0000-0000-000000000000" \
  --step-id "B2C3D4E5-0000-0000-0000-000000000000" \
  --description "Status is active" \
  --key "status" \
  --comparison-type equal \
  --expected-value "active"

# Check key exists and save value to environment
QampanionCLI create-comparison-parameter \
  --project "/path/to/Project.qpn" \
  --test-case-id "A1B2C3D4-0000-0000-0000-000000000000" \
  --step-id "B2C3D4E5-0000-0000-0000-000000000000" \
  --description "User ID exists" \
  --key "user.id" \
  --comparison-type exists \
  --environment-key "userId" \
  --json

create-script-step

Create a new bash script step in an existing test case.

Parameter	Required	Description
--project	Yes	Path to the .qpn project file.
--test-case-id	Yes	Test case ID. Use get-test-cases to find it.
--description	Yes	Description of the new step.
--script	Yes	Bash script content to execute.
--json	No	Print the result as JSON.

Example:

QampanionCLI create-script-step \
  --project "/path/to/Project.qpn" \
  --test-case-id "A1B2C3D4-0000-0000-0000-000000000000" \
  --description "Clean build artifacts" \
  --script "rm -rf /tmp/build-output && echo 'cleaned'" \
  --json

create-excluded-zone

Create a new excluded zone — a screen area that is ignored during snapshot comparison. Use it for non-deterministic content (time, animations, random data). Coordinates use the same device pixel space as get-ui-hierarchy.

Create a local zone for one step, or a global zone for the whole test case. A global zone is saved to the test case settings and copied into every existing default step.

Parameter	Required	Description
--project	Yes	Path to the .qpn project file.
--test-case-id	Yes	Test case ID. Use get-test-cases to find it.
--step-id	Yes*	Step ID. Use get-test-case --json to find it. Not required with --global.
--description	Yes	Description of the new zone (what is ignored and why).
--x	Yes	X coordinate of the zone.
--y	Yes	Y coordinate of the zone.
--width	Yes	Width of the zone.
--height	Yes	Height of the zone.
--global	No	Create a global zone for the whole test case.
--json	No	Print the result as JSON.

Example:

# Local zone for one step (status bar area)
QampanionCLI create-excluded-zone \
  --project "/path/to/Project.qpn" \
  --test-case-id "A1B2C3D4-0000-0000-0000-000000000000" \
  --step-id "B2C3D4E5-0000-0000-0000-000000000000" \
  --description "Status Bar — time and battery change" \
  --x 0 --y 0 --width 390 --height 60

# Global zone for the whole test case (ad banner)
QampanionCLI create-excluded-zone \
  --project "/path/to/Project.qpn" \
  --test-case-id "A1B2C3D4-0000-0000-0000-000000000000" \
  --description "Ad banner — random content" \
  --x 0 --y 700 --width 390 --height 100 \
  --global \
  --json

update-excluded-zone

Update an existing excluded zone. Use it when a zone was created with wrong values. Only the passed fields are changed. A global zone is updated in the test case settings and in every step copy. Pass at least one field.

Parameter	Required	Description
--project	Yes	Path to the .qpn project file.
--test-case-id	Yes	Test case ID.
--zone-id	Yes	Excluded zone ID. Use get-test-case --json to find it.
--description	No*	New description of the zone.
--x, --y	No*	New position of the zone.
--width, --height	No*	New size of the zone.
--enabled	No*	Enable the zone.
--no-enabled	No*	Disable the zone. Do not pass together with --enabled.
--json	No	Print the result as JSON.

Example:

QampanionCLI update-excluded-zone \
  --project "/path/to/Project.qpn" \
  --test-case-id "A1B2C3D4-0000-0000-0000-000000000000" \
  --zone-id "D4E5F6A7-0000-0000-0000-000000000000" \
  --x 0 --y 50 --height 44 \
  --no-enabled

delete-excluded-zone

Delete an excluded zone by ID. The zone is removed from the test case settings and from every step copy.

Parameter	Required	Description
--project	Yes	Path to the .qpn project file.
--test-case-id	Yes	Test case ID.
--zone-id	Yes	Excluded zone ID to delete.

Example:

QampanionCLI delete-excluded-zone \
  --project "/path/to/Project.qpn" \
  --test-case-id "A1B2C3D4-0000-0000-0000-000000000000" \
  --zone-id "D4E5F6A7-0000-0000-0000-000000000000"

take-snapshot

Take a screenshot from a running device and save it as the reference snapshot for a specific test step. This snapshot will be used as the expected baseline during future test runs.

Parameter	Required	Description
--project	Yes	Path to the .qpn project file.
--device	Yes	Device ID. Use get-devices to find it.
--test-case-id	Yes	Test case ID. Use get-test-cases to find it.
--step-id	Yes	Step ID. Use get-test-case --json to find it.

Example:

QampanionCLI take-snapshot \
  --project "/path/to/Project.qpn" \
  --device "0EBECE94-2084-4F51-8591-9A82A8C3B549" \
  --test-case-id "A1B2C3D4-0000-0000-0000-000000000000" \
  --step-id "B2C3D4E5-0000-0000-0000-000000000000"

run-test-case

Run one test case on a device. The tool installs the app, launches it, and runs the test steps.

Parameter	Required	Description
--project	Yes	Path to the .qpn project file.
--bundle	Yes	Path to the .app file, or a URL to download it from.
--device	Yes	Device ID. Use get-devices to find it.
--test	Yes	Test case ID. Use get-test-cases to find it.

Example:

QampanionCLI run-test-case \
  --project "/path/to/Project.qpn" \
  --bundle "/path/to/App.app" \
  --device "0EBECE94-2084-4F51-8591-9A82A8C3B549" \
  --test "A1B2C3D4-0000-0000-0000-000000000000"

run-test-plan

Run a test plan on a device. A test plan is a group of test cases that run one by one.

Parameter	Required	Description
--project	Yes	Path to the .qpn project file.
--bundle	Yes	Path to the .app file, or a URL to download it from.
--device	Yes	Device ID. Use get-devices to find it.
--plan	Yes	Test plan ID. Use get-test-plans to find it.

Example:

QampanionCLI run-test-plan \
  --project "/path/to/Project.qpn" \
  --bundle "/path/to/App.app" \
  --device "0EBECE94-2084-4F51-8591-9A82A8C3B549" \
  --plan "EC0888D0-AED4-406C-B4F8-199625929A87"

perform-action

Perform an interactive action on a running device without running a full test case. Useful for exploratory testing and AI-assisted test creation. Coordinate values must match the device pixel space returned by get-ui-hierarchy.

Parameter	Required	Description
--project	Yes	Path to the .qpn project file (used for environment variable substitution in type actions).
--device	Yes	Device ID. Use get-devices to find it.
--type	Yes	Action type: tap, swipe, type, wait.
--x	No	X coordinate for tap action.
--y	No	Y coordinate for tap action.
--from-x	No	Start X coordinate for swipe action.
--from-y	No	Start Y coordinate for swipe action.
--to-x	No	End X coordinate for swipe action.
--to-y	No	End Y coordinate for swipe action.
--text	No	Text to input for type action.
--seconds	No	Duration in seconds for wait action.

Example:

# tap
QampanionCLI perform-action \
  --project "/path/to/Project.qpn" \
  --device "0EBECE94-2084-4F51-8591-9A82A8C3B549" \
  --type tap \
  --x 319 --y 406

# swipe
QampanionCLI perform-action \
  --project "/path/to/Project.qpn" \
  --device "0EBECE94-2084-4F51-8591-9A82A8C3B549" \
  --type swipe \
  --from-x 500 --from-y 1500 --to-x 500 --to-y 500

# type
QampanionCLI perform-action \
  --project "/path/to/Project.qpn" \
  --device "0EBECE94-2084-4F51-8591-9A82A8C3B549" \
  --type type \
  --text "user@example.com"

# wait
QampanionCLI perform-action \
  --project "/path/to/Project.qpn" \
  --device "0EBECE94-2084-4F51-8591-9A82A8C3B549" \
  --type wait \
  --seconds 2

launch-app

Install and launch an application on a device. Boots the device automatically if it is not running. Pass --reinstall to uninstall the existing version before installing.

Parameter	Required	Description
--device	Yes	Device ID. Use get-devices to find it.
--bundle	Yes	URL to the application bundle (local path or http(s):// URL).
--reinstall	No	Uninstall the app before installing (disabled by default).

Example:

# Just install and launch (default)
QampanionCLI launch-app \
  --device "0EBECE94-2084-4F51-8591-9A82A8C3B549" \
  --bundle "/path/to/App.app"

# Full reinstall: uninstall, then install and launch
QampanionCLI launch-app \
  --device "0EBECE94-2084-4F51-8591-9A82A8C3B549" \
  --bundle "https://example.com/App.zip" \
  --reinstall