Reference

Look up the details here: the ways to install the securechain CLI, its commands, options, exit codes, and configuration file, the access tokens, the REST API, and the MCP server. To set up the CLI for the first time, read Get started.

This page describes version 0.1.22 of the CLI. securechain version prints the version that you have.

Install the CLI #

The CLI is one file. Select the method that fits your computer or your CI job:

curl -fsSL https://securechain.tuxcare.com/get/securechain | sh

brew install tuxcare/tap/securechain

npm install --global @tuxcare/securechain

npx @tuxcare/securechain sca

pipx install securechain

uvx securechain sca

docker run --rm -v "$PWD":/work -w /work -e SECURECHAIN_PORTAL_TOKEN tuxcare/securechain:latest-toolchains sca

curl -fsSL https://securechain.tuxcare.com/apt/tuxcare-securechain.gpg | sudo tee /etc/apt/keyrings/tuxcare-securechain.gpg >/dev/null
curl -fsSL https://securechain.tuxcare.com/apt/securechain.sources | sudo tee /etc/apt/sources.list.d/securechain.sources >/dev/null
sudo apt-get update && sudo apt-get install -y securechain

sudo curl -fsSL -o /etc/yum.repos.d/securechain.repo https://securechain.tuxcare.com/yum/securechain.repo
sudo dnf install -y securechain

<pluginRepositories>
  <pluginRepository>
    <id>tuxcare</id>
    <url>https://artifacts.tuxcare.com/repository/maven-plugin-securechain/</url>
    <releases><enabled>true</enabled></releases>
    <snapshots><enabled>false</enabled></snapshots>
  </pluginRepository>
</pluginRepositories>

<plugin>
  <groupId>com.tuxcare</groupId>
  <artifactId>securechain-maven-plugin</artifactId>
  <version>0.1.0</version>
  <executions>
    <execution><goals><goal>check</goal></goals><phase>verify</phase></execution>
  </executions>
</plugin>

mvn com.tuxcare:securechain-maven-plugin:check

pluginManagement {
    repositories {
        maven { url = uri("https://artifacts.tuxcare.com/repository/maven-plugin-securechain/") }
        gradlePluginPortal()
    }
}

plugins {
    id("com.tuxcare.securechain") version "0.1.0"
}

./gradlew securechainCheck

curl -fsSLO https://securechain.tuxcare.com/get/latest/securechain-linux-amd64
curl -fsSLO https://securechain.tuxcare.com/get/latest/checksums.txt
sha256sum --check --ignore-missing checksums.txt
install -m 0755 securechain-linux-amd64 /usr/local/bin/securechain

Then check the installation:

securechain version

Upgrade the CLI #

When a newer release is out, the CLI prints a warning on each run that connects to your workspace. When the CLI is older than the oldest version that the portal accepts, the CLI stops and tells you to upgrade. To upgrade, run:

securechain upgrade

• upgrade finds the method that installed the CLI. It needs no token and no project.
• For Homebrew, npm, pipx, uv, the install script, and a manual download on Linux or macOS, it prints the step and runs it.
• For apt, dnf, Docker, Maven, and Gradle, it prints the step only. Do the step yourself: apt and dnf need root, a Docker image needs a new pull or a new tag, and the Maven and Gradle plugins use the version that your build file names.

Sign in the CLI #

The CLI uses one secret: an access token of your workspace.

On your computer

Run securechain auth login. The CLI shows a link and a code, and opens the link in your browser. Sign in, check that the page shows the same code, select your workspace, and select Approve. The CLI keeps the token in the keychain of your computer. Over SSH, or on a computer with no browser, open the link on another device.

In CI

Make a token in the portal and keep it in a masked CI variable with the name SECURECHAIN_PORTAL_TOKEN. The CLI reads the variable and writes the token nowhere. In a CI job, the browser sign-in stops with exit code 2. See Get started: CI/CD.

• The CLI has no option for the token: a token on the command line shows in the process list and in the shell history.
• When SECURECHAIN_PORTAL_TOKEN is set, the CLI uses it, not the token in the keychain.
• The CLI finds your workspace from the token. The portal address is https://sc.tuxcare.cloud. You do not type the address of your workspace.
• A browser sign-in makes a token with the name CLI login: computer on the Access tokens page. The token has your role.
• To make sure that a job sends to the correct workspace, set --tenant name, the variable SECURECHAIN_TENANT, or the key tenant in .securechain.yaml. When the token belongs to another workspace, the CLI stops with exit code 3 and sends nothing.

Commands #

• securechain --help lists the commands. securechain sca --help lists the options of one command.
• Each command runs in the current directory. --dir path selects another project root.
• harden, update, init, and unharden take --dry-run: they print the change and write nothing.

sca and sbom read the lockfiles of these ecosystems: npm, pnpm, Yarn, Bun, Deno, pip, uv, Poetry, PDM, Pipenv, conda, Maven, Gradle, Go, Cargo, Composer, Bundler, NuGet, Paket, Julia, Mix, Pub, SwiftPM, CocoaPods, Stack, and Cabal. harden and check work for JavaScript and Python projects, and in part for Deno. Maven and Gradle need a BOM file from TuxCare. See TuxCare builds.

Options of sca and compare #

Exit codes #

Code 1 is the result of a gate. Each other code that is not 0 means that the run did not finish.

The file .securechain.yaml #

securechain init writes this file into the project root. Commit it. It holds no secret. The CLI refuses a key that it does not know, with exit code 2, so a typo does not go unseen.

Access tokens #

A token lets a program use your workspace: the CLI, a CI job, a script, or an AI assistant. Open Access tokens in the workspace menu, type a Name that tells where the token is used, select the rights, set an expiry, and select Mint token.

• A token starts with tuxr_ and the name of your workspace.
• The table shows the last four characters, the rights, the creation date, the last use, and the expiry of each token. Select Revoke to stop a token at once. A revoked token cannot come back.
• The Last CLI column shows the CLI version of the newest scan that the token sent. older than marks an old CLI. Use it to find a CI job that needs an upgrade.
• The Browser sessions table lists your sign-ins. Select Sign out on a row to end that session.

Rights #

The rights of a token are two lists:

• Channels: how the token connects. CLI is the securechain CLI. API is the REST API. MCP is the MCP server for AI assistants.
• Permissions: what the token can do. submit sends scans. read reads repositories, scans, and findings. write changes things: triage, the default branch, and the settings. poll is for scan workers only: do not give it to a CI token.

Select a preset, or select Custom and tick each channel and permission:

• A token never does more than the role of its user. A viewer can only read, so a token of a viewer cannot send scans. The page shows only the presets that your role can give.
• The CLI channel is always on. An admin must turn on the API and MCP channels for the workspace.
• You cannot change the rights of a token. Revoke it and make a new one.

Scope #

An admin selects a Scope. The scope limits what a token can see on every channel. Use the smallest scope that does the job:

A member or a viewer makes tokens for their own user only, and does not see the Scope list. A repository or department token cannot read other repositories, and it cannot make, list, or revoke tokens.

Expiry #

Set a date in Expires, or leave the field empty for a token that does not expire. The token stops at the end of that day in the time zone of your browser.

• An expired token gets the same answer as a revoked token: 401 unknown or revoked token. The table marks it expired.
• You cannot change the expiry. To replace a token: make the new token, change the CI secret, run the pipeline, then revoke the old token.
• A token that expires cannot make a token that expires later, or a token with no expiry.

API and MCP #

Programs can use your workspace in two more ways:

• The REST API at /api/v1, for scripts, dashboards, and other tools.
• The MCP server at /mcp, for AI assistants such as Claude Code and Cursor. MCP is the Model Context Protocol.

Both are off in a new workspace. Each one needs a switch that an admin turns on, and a token with that channel in its rights.

Turn the API or MCP on #

1. As an admin, open Settings › API and MCP access.
2. Select the switch of API access or MCP access. It changes from Off to On, and the page shows Saved.
3. Copy the API base URL or the MCP URL from the same section.
4. On the Access tokens page, make a token with a preset for that channel.

• When you turn a switch off, every token stops on that channel at once. The other channels continue to work.
• The CLI and the browser work with both switches off.
• If the section has no switch for a channel, the channel is not available for your workspace. Contact TuxCare.

The REST API #

The base URL is https://name.sc.tuxcare.cloud/api/v1. Send the token in the Authorization header. The API does not accept a token in the URL.

curl -fsS \
  -H "Authorization: Bearer $SECURECHAIN_API_TOKEN" \
  "https://name.sc.tuxcare.cloud/api/v1/repos?limit=20"

• A GET request needs the read permission. Any other method needs the write permission.
• The OpenAPI document at /api/v1/openapi.json lists each route, its permission, and the role that it needs. It needs no token.
• The role and the scope of the token apply, the same as in the browser. The rate limit of each token also applies.
• Useful routes: the exports (/api/v1/export/findings), the compliance report (/api/v1/repos/{id}/report), and the VEX file of a release (/api/v1/releases/{id}/vex).

The MCP server #

The MCP URL is https://name.sc.tuxcare.cloud/mcp. Use a token with the AI assistant preset, or AI assistant with triage if the assistant may triage findings. Each person uses a token of their own user.

Claude Code:

claude mcp add --transport http securechain https://name.sc.tuxcare.cloud/mcp \
  --header "Authorization: Bearer <token>"

Cursor: add the server to ~/.cursor/mcp.json, or to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "securechain": {
      "url": "https://name.sc.tuxcare.cloud/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Do not commit a file that holds a token. The server gives the assistant these tools:

• A slot is one project path and one set of ecosystems. A branch of a monorepo can have many slots. get_repo lists the scan id of each slot, and the other tools take a scan id to select a slot.
• A list tool returns 50 rows by default and 100 at most. The assistant asks for the next rows when it needs them.
• When a tool fails, for example because a finding is outside the scope of the token, the assistant gets one sentence that tells why.

When the portal refuses a request #

An AI assistant shows a 401, 403, or 404 as a connection error.

Next: Administration