CLI Integration

Connect the threatcl CLI tool to your Threatcl Cloud account for the best of both worlds: local file editing with cloud collaboration and storage.

Step 1: Install the CLI

Install the threatcl CLI using your preferred method:

Homebrew (macOS/Linux)

brew install threatcl

Go Install

go install github.com/threatcl/threatcl/cmd/threatcl@latest

Docker

docker run --rm -it ghcr.io/threatcl/threatcl:latest

Binary Download

Download the latest release for your platform from:

https://github.com/threatcl/threatcl/releases

Step 2: Authenticate with Threatcl Cloud

Connect your CLI to your Threatcl Cloud account using an API token:

Option A: API Token

Create a new API token from your Settings page, then add it to the CLI:

threatcl cloud token add

Option B: Browser Login

Alternatively, use the login command which will give you a URL to visit in your browser:

threatcl cloud login

Test the Connection

Verify your authentication is working:

threatcl cloud whoami

This will show you information about your authenticated token, including your organization.

Step 3: Basic Cloud Commands

Key commands for working with Threatcl Cloud:

List Threat Models

List all threat models in your organization:

$ threatcl cloud threatmodels
====================================================================================================
  Threat Models
====================================================================================================

ID                                   Name       Slug         Status   Version
----------------------------------------------------------------------------------------------------
fad8d654-3090-4346-9474-51d3fa565ff9 New        new          draft    1.0.1
b5b0171c-d777-45bd-958e-da59511d58ed TM         tm-tm        draft    1.0.0
b064ec8e-9e94-4890-b46b-18cd059d132d Upload     upload       draft    1.0.0
5411e4bd-3a72-4021-9451-8812e45da6e8 Test       test         draft

View Threat Model Information

View detailed information about a specific threat model using its slug:

$ threatcl cloud threatmodel -model-id new
====================================================================================================
  Threat Model
====================================================================================================

ID:              fad8d654-3090-4346-9474-51d3fa565ff9
Name:            New
Slug:            new
Description:     A historic castle
Status:          draft
Version:         1.0.1
Asset Count:     1
Threat Count:    1
Control Count:   1
Data Flow Count: 0
Use Case Count:  1
Exclusion Count: 0
Third Party Dependency Count: 0
Created At:      2026-02-09T19:39:16.149001+08:00
Updated At:      2026-02-09T20:43:56.904785+08:00

You can also download the threat model HCL file by adding the -download    flag:

threatcl cloud threatmodel -model-id new -download=my-app.hcl

List and Download Previous Versions

View the version history for a threat model:

threatcl cloud threatmodel versions -model-id new

Download a specific previous version:

threatcl cloud threatmodel versions -model-id new -version 1.0.1 -download previous.hcl

Searching Threats and Controls

Search across your threat models to find specific threats or controls using various filters. By default, searches return threats:

$ threatcl cloud search -impacts "Confidentiality"

You can filter threats by STRIDE categories, impact types, or whether they have associated controls:

# Filter by STRIDE categories
$ threatcl cloud search -stride "Tampering,Info Disclosure"

# Find threats that don't have any controls
$ threatcl cloud search -has-controls=false

# Combine multiple filters
$ threatcl cloud search -impacts "Confidentiality" -stride "Info Disclosure" -has-controls=true

To search for controls instead, use the -type    flag:

# Search all controls
$ threatcl cloud search -type controls

# Find only implemented controls
$ threatcl cloud search -type controls -implemented=true

You can also scope searches to a specific threat model or organization:

$ threatcl cloud search -threatmodel-id "550e8400-e29b-41d4-a716-446655440000"
$ threatcl cloud search -org-id "01a8b411-decf-47ae-b804-0f959cc16f21"

Step 4: Validating and Pushing to Threatcl Cloud

Key commands for validating a HCL threat model with your cloud environment, and pushing new versions.

Validate Threat Models

If your threat model HCL file has a backend    block, the threatcl cloud validate    command can be used to validate that your local file has:

• A correct organization    attribute
• Optionally, a correct threatmodel    attribute

For example, save a new local HCL file with the following content:

spec_version = "0.2.4"

backend "threatcl-cloud" {
    organization = "start-here"
}

threatmodel "My App" {
    description = "This is a special app"
    author = "my name"

    threat "Unauthorized Access" {
        description = "Attacker gains access to user accounts"
        impacts = ["Confidentiality"]
        stride = ["Spoofing", "Elevation of Privilege"]

        control "SSO" {
            description = "Integrate with corporate Single Sign-on"
            implemented = false
            risk_reduction = 75
        }
    }
}

When you run threatcl cloud validate <file>   , if the organization slug doesn't match, you'll see an error like:

$ threatcl cloud validate model.hcl
❌ validation failed: User is not a member of organization 'start-here'.
  Available organizations:
  - Daft Punk (slug: daft, role: owner)
  - Acme (slug: acme, role: admin)

Update your organization    attribute to match one of your valid slugs ‐ in the example above, this would be acme   . Then run validate again:

$ threatcl cloud validate model.hcl
✓ Organization is valid

Your current token, and this file, are now mapped to an organization.

Pushing Threat Models

Now that you've validated the backend block, you can push your threat model with threatcl cloud push <file>   . This will:

• Create a new threat model in the organization
• Update the HCL to include the threatmodel    attribute in the backend    block
• Upload this HCL as a new version

$ threatcl cloud push model.hcl
Creating new threat model 'My App'...
✓ Created threat model 'My App' (slug: my-app)
✓ Updated model.hcl with threatmodel = "my-app"
Uploading threat model...
✓ Successfully pushed threat model from model.hcl

Once a threatcl HCL file has a valid organization    and threatmodel    attribute in the backend    block, any future push commands will compare and only push a new version if differences are detected.

$ threatcl cloud push model.hcl
✓ Cloud version matches local version (v1.0.0), not pushing

Now that you can push new versions to Threatcl Cloud, you're ready to integrate with ci/cd workflows

Step 5: Integrate into your CI/CD

Once you've installed the threatcl    binary into your pipelines, you can run these same commands to push your threat models into the cloud. To support CI/CD environments, the threatcl cloud    commands also support some environment variables to streamline authentication.

Environment Variables

GitHub Action

Alternatively, for GitHub users, there is an action that can be used:

name: threatcl cloud validate test

on:
  push:
    branches:
      - main
    workflow_dispatch:

jobs:
  threatcl-cloud-validate:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Threatcl cloud validate
        uses: threatcl/threatcl-action@v0.0.6
        with:
          command: 'cloud'
          files: 'acme.hcl'
        env:
          THREATCL_API_TOKEN: ${{ secrets.TCL_TOKEN }}
          THREATCL_CLOUD_ORG: ${{ secrets.TCL_ORG_ID }}
      - name: Threatcl cloud push
        uses: threatcl/threatcl-action@v0.0.6
        with:
          command: 'cloud'
          cloud-command: 'push'
          files: 'acme.hcl'
        env:
          THREATCL_API_TOKEN: ${{ secrets.TCL_TOKEN }}
          THREATCL_CLOUD_ORG: ${{ secrets.TCL_ORG_ID }}

Additional Resources

• threatcl CLI Documentation
• GitHub Repository
• Example Threat Models
• Manage API Tokens

Next Steps

MCP Connector