# Connecting via the Seal CLI in CI

When you cannot grant Seal read access to your source code, but the Seal CLI can run inside your CI/CD pipeline, the CLI itself becomes Seal's window into your packages. The Seal Project enters [CLI discovery mode](/new-documentation/new-docs/package-discovery-mode/cli.md) the first time the CLI runs against it.

This chapter is the minimum setup to wire CLI-driven discovery in. The deeper, per-platform CI integration mechanics (GitHub Actions, GitLab CI, Azure DevOps Pipelines, Jenkins, CircleCI, and others) live in [Seal Apps via the Seal CLI in CI/CD](https://github.com/seal-community/gitbook/blob/main/new-docs/setup-apps-os/cli-in-cicd/README.md).

## Before you start

* A **production** [token](/new-documentation/new-docs/tokens.md), stored in your CI's secret manager.
* A **Project ID** for the Seal Project. If a project with that Project ID does not exist in your tenant, it is created automatically the first time the CLI runs.
* A CI environment that can install the Seal CLI and reach Seal's servers over HTTPS.

{% hint style="info" %}
**Project ID, not project name.** A Seal Project has two distinct identifiers: a human-readable **name** (mutable, allows spaces, used in the UI) and a machine-readable **Project ID** (immutable, limited to letters, numbers, dots, hyphens, and underscores, used in the API and the CLI). The two are independent. The CLI works against the Project ID; the display name has no effect on a CLI run.
{% endhint %}

## Steps

1. **Install the Seal CLI** in your CI runner. The cross-platform install steps are in [Installing the Seal CLI](https://github.com/seal-community/gitbook/blob/main/new-docs/setup-apps-os/cli-in-cicd/installing-the-cli.md).
2. **Configure environment variables** for the pipeline step that runs the CLI:
   * `SEAL_TOKEN`: the production token, pulled from your CI's secret store.
   * `SEAL_PROJECT`: the Seal Project's Project ID.
3. **Run `seal scan`** in the working directory of the project you want to scan:

   ```bash
   seal scan
   ```

   The first run creates the Seal Project (if needed) with the supplied Project ID, and populates it with discovered packages. Subsequent runs with the same `SEAL_PROJECT` value attach to the same project and produce fresh signal.

## Verify

* On the **Projects** page, your Seal Project appears with **CLI** as its package discovery mode.
* On the **Protection** page's **Vulnerable packages** tab, the packages from your manifest appear as Seal scans them.

## Troubleshooting

**The CLI fails with an authentication error.** Confirm `SEAL_TOKEN` is set in the pipeline step's environment, that the token has not been revoked, and that you are using a production token. Activity authenticated with a development token is filtered out of the Protection page by default, so the scan can succeed but the results may not appear where you expect.

**The Seal Project does not appear on the Projects page.** Either the CLI did not finish (check the pipeline log) or the run authenticated against a different tenant than you are looking at.

**The CLI rejects the value of `SEAL_PROJECT`.** Project IDs are restricted to letters, numbers, dots, hyphens, and underscores (no spaces or other punctuation), and capped at 255 characters. Pick a value that fits the rules.

**Two pipelines are clobbering each other's results.** Both pipelines are running with the same `SEAL_PROJECT` value, so they are writing into the same Seal Project. Give each pipeline its own Project ID. See [Anti-patterns in Creating a Seal Project](/new-documentation/new-docs/creating-a-seal-project.md#anti-patterns).

## Related

* [CLI mode](/new-documentation/new-docs/package-discovery-mode/cli.md): the discovery mode this chapter sets up.
* [Managing tokens](/new-documentation/new-docs/tokens.md): production vs development tokens, and what each one is tracked against.
* [Seal Apps via the Seal CLI in CI/CD](https://github.com/seal-community/gitbook/blob/main/new-docs/setup-apps-os/cli-in-cicd/README.md): the per-platform CI integrations and the broader fix-mode story.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sealsecurity.io/new-documentation/new-docs/cli-in-ci.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.