CLI Overview

The Testform Command Line Interface (CLI) is the central operational tool for managing your test infrastructure as code. Designed following the conventions and philosophy of HashiCorp’s Terraform, it provides an intuitive, predictable, and consistent workflow.

Command Syntax

testform [global options] <subcommand> [options] [arguments]

Global Options

Global options can be provided before any subcommand:

Global Option	Alias	Description
`-chdir=DIR`	`-C`	Switches working directory to `DIR` before executing the command.
`-scope=SCOPE`	`-s`	Limits execution to `testcase`, `testrun`, or `testplan`.
`-project-id=ID`	—	Overrides the default GitHub Projects V2 ID configured in `main.yml`.
`-no-color`	—	Disables ANSI color escapes (ideal for plain log aggregators).
`-json`	—	Emits machine-readable JSON output for automated scripting and CI/CD pipelines.
`-help`	`-h`	Displays detailed usage and help text for any command.
`-version`	`-v`	Prints the installed Testform version.

Scope-First Syntax

Testform allows placing the scope identifier before the command for a more natural CLI syntax:

# Standard syntax:
testform plan -scope=testcase

# Equivalent scope-first syntax:
testform testcase plan
testform testrun apply
testform testplan destroy

Operational Directories

Testform automatically manages the local .testform/ directory to store backend metadata, cached modules, and custom extensions, as well as the global ~/.testform.d/ directory for API access credentials. See The .testform and ~/.testform.d Directories for complete details.

Complete Command Index

Core Workflow

Lifecycle commands for provisioning and managing test infrastructure:

Command	Description
`testform init`	Prepares the working directory, downloads plugins, and configures the backend.
`testform plan`	Shows changes required by the current configuration against the state.
`testform apply`	Creates or updates test resources on remote providers.
`testform refresh`	Updates local state to match remote issue trackers.
`testform destroy`	Safely tears down previously-created test resources.

Developer Tools

Inspection, diagnostics, validation, and reporting utilities:

Command	Description
`testform validate`	Statically checks configuration syntax and governance rules.
`testform fmt`	Rewrites Gherkin feature files and configurations to standard style.
`testform diff`	Shows drift between local configuration and state ledger.
`testform show`	Shows the current state or a saved plan in human-readable or JSON form.
`testform query`	Queries and filters managed test resources in state using expressions.
`testform policy`	Inspects, enables, or disables quality governance policies.
`testform modules`	Shows all declared modules and resolved versions in the workspace.
`testform providers`	Displays provider requirements tree and resource schemas.
`testform functions`	Inspects and evaluates built-in expression functions.
`testform print`	Parses a `.feature` file and prints its JSON Abstract Syntax Tree (AST).
`testform graph`	Generates a Graphviz (DOT), Mermaid, or tree visual dependency graph.
`testform report`	Generates multi-dimensional reports in Markdown, Word, Excel, or JSON.
`testform suite`	Manages test suites and execution files (`init`, `-fill`, `-link`, `-mark`).

Storage & State

State ledger inspection and manipulation:

Command	Description
`testform state`	Advanced state management (`list`, `show`, `mv`, `rm`, `pull`, `push`).
`testform output`	Reads and prints output values saved in the state file.
`testform import`	Associates existing remote entities with Testform resources.
`testform taint`	Marks a resource instance as degraded to force replacement on next apply.
`testform untaint`	Removes the tainted status from a resource instance in state.
`testform force-unlock`	Manually releases an abandoned state lock on the current workspace.

Workspaces & Sessions

Environments, authentication, and runtime:

Command	Description
`testform workspace`	Manages multiple isolated workspaces (`list`, `new`, `select`, `delete`).
`testform login`	Obtains and saves API credentials for a remote host.
`testform logout`	Removes locally-stored credentials for a remote host.
`testform ephemeral`	Manages temporary CI/CD test sandboxes.
`testform version`	Displays current Testform version and checks for upgrades.