--- title: "Scan Overrides" slug: "scan-overrides" description: "Override scan configurations for a particular scan run from the CLI. you can override target URL, authentication hooks and API specifications." tags: ["API Specifications", "Scan Overrides", "Traceable CLI"] updated: 2026-09-08T09:37:07Z published: 2026-09-08T09:37:07Z canonical: "traceabledocs.document360.io/scan-overrides" --- > ## 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. # Scan Overrides A scan that you create on the Traceable platform holds the baseline configuration for that scan. Scan overrides enable you to change specific parts of that baseline for a single run via the Traceable CLI, without editing the scan itself or creating a new one. ## What you will learn from this topic By the end of this topic, you will be able to understand: - How to override the target URL, authentication hooks, and API specifications of a scan run. - How to queue a scan to a remote runner and apply overrides. --- ## Before you begin Make a note of the following before you use scan overrides: - Ensure that you are using Traceable CLI version *2.8.0 or later*. For more information, see [CLI Pre-checks and Installation](https://docs.traceable.ai/docs/cli-installation). - Make sure you note the name or ID of the scan you wish to override. For more information, see [Retrieve scan name](/v1/docs/clone-scan-overrides#retrieve-scan-name1) and [Retrieve scan ID](/v1/docs/clone-scan-overrides#retrieve-scan-id1). --- ## Understand scan overrides The scan on the Traceable platform provides the baseline configuration. Passing a CLI flag overrides its setting for that run only, and you can pass multiple flags in the same run. Any setting you do not override keeps the scan's original configuration. When a setting is defined in more than one place, Traceable resolves the configuration in the following order of precedence, from highest to lowest: **CLI Flag > Config file > Platform scan configuration > Platform defaults** ### Retrieve scan name You can find the name of your scan by following the given steps: 1. Navigate to **Testing → Scans.** 2. Copy the scan name from the corresponding row. ### Retrieve scan ID You can find the scan ID for your scan by following the given steps: 1. Navigate to **Testing → Scans.** 2. Select your scan. 3. Copy the scan ID from the URL. ![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/find scan id(1).png) Retrieve Scan ID ### Supported commands Scan overrides apply to the following commands: ```bash traceable ast scan initAndRun --scan-name [override flags] traceable ast scan initAndRun --scan-id [override flags] traceable ast scan queue --scan-name [override flags] traceable ast scan queue --scan-id [override flags] ``` > [!NOTE] > Note > > - Replace `<scan-name>` or `<scan-id>` with the name or ID of your scan, respectively. For more information, see [Retrieve scan name](/v1/docs/clone-scan-overrides#retrieve-scan-name) and [Retrieve scan ID](/v1/docs/clone-scan-overrides#retrieve-scan-id). > - You must provide either `--scan-name` or `--scan-id`. The two flags are mutually exclusive. ### Use scan overrides The following overrides are supported: - [Override the target URL](/v1/docs/clone-scan-overrides#override-the-target-url) - [Override authentication hooks](/v1/docs/clone-scan-overrides#override-authentication-hooks) - [Override API specifications](/v1/docs/clone-scan-overrides#override-api-specifications) #### Override the target URL Use the `--target-url <url>` flag to override the target URL of the scan. The `<url>` value must be a valid `http://` or `https://` URL. | Input | Behavior | | --- | --- | | Flag omitted | Traceable uses the platform scan configuration. | | `--target-url "https://example.com"` | Traceable overrides the platform scan's target URL. | The following code snippet illustrates how to override the target URL: ```bash traceable ast scan initAndRun --scan-name my-scan --target-url https://staging.example.com ``` #### Override authentication hooks You can reference authentication hooks either by `—-hook-names` or by `—-hook-ids`. You can retrieve the hook name by navigating to **Testing → Authentications →** **Name** column (find your authentication). | Flag | Type | Description | | --- | --- | --- | | `--hook-names <names>` | Comma-separated string | References hooks by name. | | `--hook-ids <uuids>` | Comma-separated UUIDs | References hooks by ID. | > [!NOTE] > Note > > `--hook-names` and `--hook-ids` are mutually exclusive. The following table shows different use cases of the flag: | Input | Behavior | | --- | --- | | Flag omitted | Traceable uses the platform scan configuration. | | `--hook-names ""` | Traceable clears all hooks. The scan run executes without authentication. | | `--hook-names "hookA,hookB"` | Traceable overrides the platform scan's hooks with the specified hooks. | > [!NOTE] > Note > > `—-hook-names` can be used interchangeably with `—-hook-ids`for the above set of commands. The following code snippets give examples of different ways you can override authentication hooks: ```bash # Override with specific hooks by name traceable ast scan initAndRun --scan-name my-scan --hook-names "staging-auth" # Override with specific hooks by ID traceable ast scan initAndRun --scan-name my-scan --hook-ids "uuid-1,uuid-2" # Clear all hooks traceable ast scan initAndRun --scan-name my-scan --hook-names "" ``` Traceable executes the hooks in the order that you specify. If a hook name or ID does not exist on the platform, the scan errors out. #### Override API specifications Specification overrides replace the platform scan's traffic configuration. You can override only one specification type per scan run. For more information on traffic types, see [Understanding Scans and Traffic Types](/v1/docs/ast-scans). **Retrieve API specification file paths** You can find the file path to your API specifications in your project’s GitHub repository. The following are the accepted file path formats: - Absolute: `/path/to/spec.yaml` - Relative: `./specs/openapi.yaml` - Directory: `./specs/` (files with matching extensions are recursively collected) Local files are automatically uploaded to the platform before the scan starts, if provided. **Retrieve API specification IDs** You can find the API specification IDs by following the steps given below: 1. Navigate to **Discovery → Documentation**. 2. Select the API specification file for which you wish to obtain the ID. 3. Copy the API ID from the URL. ![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/find auth hook id new.png) Retrieve API spec ID Overrides are supported for the following specification types: - OpenAPI - GraphQL - WSDL - Postman **OpenAPI** The following table describes the available flags for OpenAPI: | Flag | Type | Description | | --- | --- | --- | | `--openapi-spec-files <paths>` | Comma-separated file or directory paths | Traceable uploads local files automatically. Directories are walked recursively for `.json`, `.yml`, and `.yaml` files. | | `--openapi-spec-ids <uuids>` | Comma-separated UUIDs | References specifications that are already on the platform. | > [!NOTE] > Note > > `--openapi-spec-files` and `--openapi-spec-ids` are mutually exclusive. You cannot use both together. **GraphQL** The following table describes the available flags for GraphQL: | Flag | Type | Description | | --- | --- | --- | | `--graphql-schema-files <paths>` | Comma-separated file or directory paths | Traceable uploads local SDL files automatically. Traceable walks directories recursively for `.graphql` and `.gql` files. | | `--graphql-schema-ids <uuids>` | Comma-separated UUIDs | References schemas that are already on the platform. | > [!NOTE] > Note > > `--graphql-schema-files` and `--graphql-schema-ids` are mutually exclusive. You cannot use both together. **WSDL** The following table describes the available flags for WSDL: | Flag | Type | Description | | --- | --- | --- | | `--wsdl-files <paths>` | Comma-separated file or directory paths | Traceable uploads local files automatically. Traceable walks directories recursively for `.wsdl` files. | | `--wsdl-ids <uuids>` | Comma-separated UUIDs | References specifications that are already on the platform. | > [!NOTE] > Note > > `--wsdl-files` and `--wsdl-ids` are mutually exclusive. You cannot use both together. **Postman** Postman overrides differ from other specification types. They consist of two separate artifacts, a collection and an environment, and each accepts a single value rather than a comma-separated list. For more information on Postman collections, see [Postman collections with AST](/v1/docs/postman-collections-with-ast). The following table describes the available flags for Postman: | Flag | Type | Description | | --- | --- | --- | | `--postman-collection <path>` | Single file path | The collection file. Traceable uploads it automatically. | | `--postman-collection-id <uuid>` | Single UUID | References a collection on the platform. | | `--postman-environment <path>` | Single file path | The environment file. Traceable uploads it automatically. | | `--postman-environment-id <uuid>` | Single UUID | References an environment on the platform. | > [!NOTE] > Note > > Exclusivity applies within each pair, not across them. The following pairs are mutually exclusive: > > - `--postman-collection` and `--postman-collection-id` > - `--postman-environment` and `--postman-environment-id` > > Cross-pair combinations are allowed, such as `--postman-collection-id <uuid> --postman-environment ./env.json`. --- ## Use scan overrides in CI/CD Overrides enable you to customize scan configuration at runtime without changing the underlying scan definition. Pass override values as CLI flags to adapt the scan to your execution environment. Because overrides are supported directly by the Traceable CLI, they can be used with any CI system that can invoke the CLI. The following options are available depending on your setup: - **GitHub Actions** — The Traceable AST GitHub Action exposes every override flag through the `additional_cli_options` input. For supported actions, their inputs, and sample workflows, see [GitHub Actions](/v1/docs/github-actions-v2-1). - **Any other CI system** — Invoke the CLI directly and pass overrides as flags. For command sequences and exit code handling, see [Run scan from CLI](/v1/docs/run-scan-from-cli). SDL stands for Schema Definition Language. In the context of GraphQL, SDLis a way to define the schema of GraphQL APIs using a human-readable syntax. It is used to specify the types, queries, and mutations available in the API.