--- title: "Run a Scan from CLI" slug: "run-scan-from-cli" description: "Run a scan from the Traceable CLI. Pause and resume a scan, queue a scan to a remote runner from the CLI" tags: ["Scan Lifecycle", "Traceable CLI"] updated: 2026-09-08T07:47:53Z published: 2026-09-08T07:47:53Z canonical: "traceabledocs.document360.io/run-scan-from-cli" --- > ## Documentation Index > Fetch the complete documentation index at: https://traceabledocs.document360.io/llms.txt > Use this file to discover all available pages before exploring further. # Run a Scan from CLI A scan is configured on the Traceable platform and can then be executed from either the platform or the CLI. Running it from the CLI enables a CI/CD pipeline to start the scan, publish its results, and gate the build on its outcome as separate steps, each returning an exit code the pipeline can act on. This topic covers what each command does and when to use it. For more information on the flags each command accepts, see [Traceable commands and options](/v1/docs/cli-installation#traceable-commands-and-options1). ## What you will learn from this topic By the end of this topic, you will be able to understand: - The commands that make up the scan lifecycle, and the order in which a pipeline runs them. - How to dispatch a scan to a runner deployed inside your own network. - Which exit codes the CLI returns, and which commands return them. - How to troubleshoot a scan that does not start or ends early. --- ## Before you begin Make a note of the following before you run a scan from the CLI: - Install the Traceable CLI. For more information, see [CLI Pre-checks and Installation](/v1/docs/cli-installation). - Make sure you create a scan on the Traceable platform, and note its name or ID. For more information, see [Creating a Scan](/v1/docs/creating-scan). - Make sure you fetch the platform access token that the CLI uses to authenticate. For more information, see [Public APIs](/v1/docs/public-apis). - Make sure you install and start at least one runner. For more information, see [Installing a Runner](/v1/docs/installing-a-runner). > [!NOTE] > Note > > Queuing a scan to remote runners requires Traceable CLI version *2.8.0* *or later*. For more information, see [CLI Pre-checks and installation](/v1/docs/cli-installation). --- ## Scan commands The scan lifecycle is split across four commands, so that a pipeline can start a scan, publish its results, and gate on its outcome as separate steps. The following table describes each command: | Command | Description | | --- | --- | | `traceable ast scan initAndRun` | Initializes and executes a scan on the machine that invokes the CLI. | | `traceable ast scan queue` | Dispatches a scan to remote Traceable runners. | | `traceable ast scan report` | Generates and publishes a report for a scan run. | | `traceable ast scan getEvaluationResult` | Returns the evaluation result for a scan run. | - **Start the scan:** Choose the command based on where the target APIs are reachable from, as described in the following table: | Command | Use it when | | --- | --- | | `initAndRun` | The scan has been created, and you need to initialize and run the scan. | | `queue` | The runner is reachable only from inside your own network. For more information, see [Runners and CLI](/v1/docs/runners). | > [!NOTE] > Note > > The scan must be configured on the Traceable platform before executing. It can then be run from either the platform or the CLI. For more information, see [Creating a Scan](/v1/docs/creating-scan). Both the commands identify the scan either by name or by ID, as shown below: ```bash traceable ast scan initAndRun --scan-name traceable ast scan initAndRun --scan-id ``` > [!NOTE] > Note > > `--scan-name` and `—-scan-id` are mutually exclusive, and you must provide at least one of them. To change the target URL, API specification, or authentication hooks for this run only, add the relevant override flags in any order. For more information, see [Scan Overrides](/v1/docs/clone-scan-overrides). - **Generate the report:** Traceable produces a report whether the run completed or was aborted: ```bash traceable ast scan report --output-format md ``` > [!NOTE] > Note > > - The default report format is markdown (`md` ). > - You can store the report using `—-output-file <path>` at your desired location. For more commands, see [Traceable commands and options](/v1/docs/cli-installation#traceable-commands-and-options1). - **Evaluate the result:** This is the step a pipeline uses to pass or fail the build: ```bash traceable ast scan getEvaluationResult ``` - **Pause or resume scan:** Traceable enables you to pause and resume scans via the CLI. Follow the steps in the tabs below to pause or resume the scan according to your requirements: Pause ScanResume Scan When you pause a scan, Traceable stops test generation for the scan. You can always resume the scan according to your requirements. To pause a scan, complete the following steps in your CLI: 1. Press `Ctrl+C` or `Command+C` to get a list of scan termination options. 2. Type `P` and click `Enter` or `Return`. Traceable pauses the scan indefinitely until you resume it. Traceable can resume a scan if it is in either of the following states: - Paused: The scan run is paused. - Aborted: The scan run is aborted. To resume a scan, you must run the following command: > [!NOTE] > Note > > The `<scan-id>` field in the below command is optional. If you skip this field, Traceable automatically selects the ID from the last scan. ```bash traceable ast scan resume --scan-id ``` ##### Caveats - Resuming a scan does not generate new test scans or plugins; it only re-runs the plugins that were partially executed or not executed in the previous run. - As Traceable may re-run some tests from plugins that were partially executed, you may see an increase in the test count. > [!NOTE] > Note > > Pause and Resume scan is available for CLI version *1.10.20* and above. To check the current CLI version, you can use the `traceable version` command. --- ## Queue scan to a remote runner The `queue` command dispatches a scan to Traceable runners deployed in your own network instead of executing it locally. The following command shows the structure of a queued scan, including runner selection, wait flags, and override flags: ```bash traceable ast scan queue --scan-name \  [--runner-ids ] [--runner-names ] [--runner-labels ] \  [--wait] [--wait-timeout ] [override flags] ``` All scan overrides, including target URL, specifications, and hooks, are supported with the `queue` command. For more information, see [Scan Overrides](/v1/docs/clone-scan-overrides). ### Runner selection Runner selection flags control which runners are eligible to pick up the scan. The following table describes the available flags: | Flag | Type | Description | | --- | --- | --- | | `--runner-ids <ids>` | Comma-separated list | Targets runners by ID. | | `--runner-names <names>` | Comma-separated list | Targets runners by name. | | `--runner-labels <labels>` | Comma-separated list | Targets runners that carry at least one of the labels. | > [!NOTE] > Note > > If you do not specify any of these flags, Traceable assigns any available runner. For more information on how labels route scans to runners, see [Installing a Runner](/v1/docs/installing-a-runner). ### Wait behavior By default, the `queue` command returns as soon as the scan is dispatched, which means no result exists for a later step to act on. The wait flags keep the command running until the scan finishes. The following table describes the available flags: | Flag | Default | Description | | --- | --- | --- | | `--wait` | false | Blocks until the scan reaches a terminal state. | | `--wait-timeout <minutes>` | — | The maximum time to wait. This flag requires `--wait`. | --- ## Exit codes Exit codes let a CI/CD pipeline act on the outcome of a scan run without parsing its output. The following table describes each code that the CLI returns: | Code | Description | | --- | --- | | 0 | The scan completed successfully, or the evaluation result is PASS. | | 1 | The evaluation result is FAIL. A policy is violated. | | 3 | The scan stopped early. It was aborted or paused, or it reached the maximum test limit. | | 6 | The evaluation is not available. No policy is configured, or the scan is incomplete. | | 99 | An unknown error occurred. | Not every command returns these codes by default. Most require you to opt in with `--exit-code`, so that a scan run does not fail a pipeline unless you intend it to. The following table describes when each command returns an exit code: | Command | Returns an exit code | | --- | --- | | `initAndRun` | When you specify `--exit-code`. | | `queue` | When you specify both `--wait` and `--exit-code`. | | `report` | When you specify `--exit-code`. | | `getEvaluationResult` | Always, based on the evaluation result. | --- ## Sample command sequences The code snippets in this section show different formats of using the scan commands on Traceable CLI. For more information on other Traceable commands, see [Traceable commands and options](/v1/docs/cli-installation#traceable-commands-and-options1). The following code snippet runs the scan, writes the report, and returns an exit code in one step: ```bash traceable ast scan initAndRun \  --scan-name my-scan \  --output-format sarif --output-file results.sarif \  --exit-code ``` Alternatively, you can separate the steps as well: ```bash traceable ast scan initAndRun --scan-name my-scan traceable ast scan report --output-format md traceable ast scan getEvaluationResult ``` You can invoke the CLI from any CI system. To use the Traceable AST GitHub Actions instead of invoking the CLI directly, see [GitHub Actions](/v1/docs/github-actions-v2-1).