Skip to content
threatcl

Managing Threat Models

Threatcl Cloud provides a full suite of commands for creating, uploading, viewing, and managing threat models in the cloud.

Listing Threat Models

The cloud threatmodels command lists all threat models in your organization.

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


ID                                   Name                           Slug                 Status     Version
----------------------------------------------------------------------------------------------------
4b6bdaf3-6a92-42f7-8edf-fe4e285151a6 My App                         my-app               draft      1.0.3
9c0e24fe-bf12-42b6-b44a-2c5ce6484e61 Test Example                   test-example         draft      1.0.21
74ec8b30-a22e-4ec8-825a-56cae7f83c8c Testing Pre-canned             testing-pre-canned   in_review  1.0.5

Viewing a Threat Model

The cloud threatmodel command retrieves and displays a single threat model from the cloud.

terminal
$ threatcl cloud threatmodel -model-id=tm_abc123

Threatmodel options

  • -model-id - the ID of the threat model to view
  • -download - download the threat model HCL to a local file
  • -overwrite - overwrite the local file if it already exists (used with -download)

Versions

The cloud threatmodel versions command lists or downloads previous versions of a threat model.

terminal
$ threatcl cloud threatmodel versions -model-id test-example


📋 Threat Model Versions
────────────────────────────────────────────────────────────────────────────────────────────────────
▶ CURRENT VERSION
  Version:    1.0.21
  Created:    2026-01-30 14:15:46
  Changed by: 4c576800-a557-4a7f-a00b-3acf6b86552b
  ID:         d35f1bba-809d-4404-bfbd-8f80650b8e91


  Version:    1.0.20
  Created:    2026-01-30 14:14:12
  Changed by: 4c576800-a557-4a7f-a00b-3acf6b86552b
  ID:         783ce76c-e0c9-424d-bb93-c1c5c7aa2c9f

Versions options

  • -model-id - the ID of the threat model
  • -download - download a specific version to the named file
  • -version - the version number to download, such as 1.0.3. Required with -download
  • -overwrite - overwrite the local file if it already exists

Delete

The cloud threatmodel delete command deletes a threat model from the cloud.

terminal
$ threatcl cloud threatmodel delete -model-id=tm_abc123

Delete options

  • -model-id - the ID of the threat model to delete

Update Status

The cloud threatmodel update-status command changes the status of a threat model.

terminal
$ threatcl cloud threatmodel update-status -model-id=tm_abc123 -status=approved

Update Status options

  • -model-id - the ID of the threat model
  • -status - the new status. One of draft, in_review, approved or archived

Creating Threat Models

The cloud create command creates a new threat model in the cloud.

terminal
$ threatcl cloud create -name "My Application" -description "My app threat model"

Create options

  • -name - required. The name of the new threat model
  • -description - a description for the threat model
  • -upload - path to an HCL file to upload as the initial content. The file must contain exactly one threat model. For a multi-file model, upload the root file here and push the child files afterwards

Uploading HCL

The cloud upload command uploads an HCL file to an existing threat model in the cloud.

terminal
$ threatcl cloud upload -model-id=tm_abc123 my-threatmodel.hcl

Upload options

  • -model-id - the ID of the threat model to upload to

Push

The cloud push command is the most common way to get local threat models into the cloud. It validates the HCL file, creates the threat model if needed, and uploads the content, all in one step.

terminal
$ threatcl cloud push model.hcl
Uploading new version to threat model 'my-app'...
✓ Successfully pushed threat model from model.hcl

Push options

  • -no-create - skip creating a new threat model if it doesn’t exist; only upload to existing models
  • -no-update-local - don’t update the local HCL file with cloud metadata after push
  • -ignore-linked-controls - skip validation of linked control references
  • -with=<glob> - parse the pushed file together with its sibling files as one set, running the server’s whole-set validation locally first. See multi-file models

Validate

The cloud validate command validates an HCL file for cloud compatibility without uploading it. This checks that the file has exactly one backend block with backend_name set to threatcl-cloud and exactly one organization, that you are a member of that organization, and that the file parses as valid HCL.

terminal
$ threatcl cloud validate model.hcl
✓ Local Threat model file matches the latest version of the cloud threat model
✓ 1 threat ref(s) validated (PUBLISHED)

When the backend block names a threatmodel slug, the content is validated server-side as well. That catches collisions only the server can see, such as a control name that only collides once a cloud ref is enriched from the library. An unreachable validate endpoint is a warning, not a failure.

This is useful for CI/CD pipelines or pre-push checks. See the Cloud Overview for details on the backend block.

Validate options

  • -diff - when the local file doesn’t match the latest cloud version, download that version and print a summary of the semantic differences, followed by a unified, git-style diff
  • -with=<glob> - parse the validated file together with its sibling files as one set, running the server’s whole-set validation locally first. See multi-file models
terminal
$ threatcl cloud validate -diff model.hcl

View

The cloud view command renders a threat model with enriched data from Threatcl Cloud, including resolved library references for threats and controls.

Controls that reference the cloud control library are enriched with their descriptions, implementation guidance, and risk reduction values. If the control has local values set (e.g., description, risk_reduction), those local values are preserved and the cloud data is not used to overwrite them.

By default, threats that reference the threat library will also include their recommended controls from the library.

terminal
$ threatcl cloud view my-threatmodel.hcl


  My Application


  Author: @me


  ## Threat Scenarios


  ### Data Breach


  Unauthorized access to sensitive data


  │ Library Ref: LIB-T-001
  │ STRIDE: Tampering, Info Disclosure


  #### Controls


  ##### Encryption at Rest (LIB-C-042)


  │ Implemented: ✅
  │ Risk Reduction: 80

Viewing a cloud threat model directly

Use -model-id to fetch and view a threat model directly from Threatcl Cloud without needing a local copy of the HCL file. You can pass either the model ID or its slug.

terminal
$ threatcl cloud view -model-id=my-threat-model

If you belong to multiple organizations, use -org-id to specify which one to fetch from:

terminal
$ threatcl cloud view -model-id=my-threat-model -org-id=<orgId>

View options

  • -model-id - fetch and view a threat model from Threatcl Cloud by ID or slug. When set, the <file> argument is not required.
  • -org-id - organization ID to use with -model-id. If not provided, uses the THREATCL_CLOUD_ORG env var or the default from your token store.
  • -raw - output raw markdown instead of the formatted display
  • -ignore-linked-controls - skip resolving linked control references from the cloud library

Export

The cloud export command exports a threat model from Threatcl Cloud with every library reference resolved.

Unlike cloud threatmodel -download, which writes the raw HCL stored in the cloud, this fetches each referenced threat, control and information asset from the cloud library and inlines its description, STRIDE, impacts, implementation guidance, risk reduction, information classification and source before rendering. The result is a standalone, portable artifact, suitable for sharing with reviewers who can’t reach the cloud library.

terminal
$ threatcl cloud export -model-id=my-app -format=md -output=my-app.md

Export options

  • -model-id - required. The threat model ID or slug to export
  • -format - the output format. One of json (the default), otm, hcl or md
  • -output - write to a file instead of STDOUT
  • -template - an overridden template file to use for md output
  • -overwrite - overwrite the output file if it already exists
  • -keep-backend - preserve the backend "threatcl-cloud" block in the output. By default it is stripped, so the export is portable
  • -include-recommended - pull each referenced threat’s library-recommended controls into the exported model. Off by default
  • -org-id - the organization to export from

Multi-file models

A cloud threat model can be split across several files, keyed by each file’s threatmodel id:

  • The file declaring the un-dotted root id, such as id = "app", is the model’s default file.
  • Each additional file declares a dotted id beneath it, such as id = "app.frontend", and typically extends the root.
  • Every file’s backend block must address the same organization and threat model.

The backend block’s segment attribute from earlier specs no longer exists. The threatmodel id alone keys each file.

Push the root file first, then its children:

terminal
$ threatcl cloud push app.hcl
$ threatcl cloud push app-frontend.hcl

Each file is parsed on its own terms, so a child whose extends target lives in another file won’t fail locally. The server validates the assembled set and stays authoritative. cloud push will refuse to create a new cloud model from a file that looks like a child segment, so push the root first.

This applies to every cloud parse path: cloud push, cloud upload, cloud create -upload, cloud validate, cloud validate -diff and cloud export.

Checking the whole set locally

Before contacting the server, cloud push and cloud validate can parse the target file together with its siblings and run the same whole-set validation the server applies: extends resolution, name and id uniqueness, reserved namespace segments, one un-dotted root id with its children beneath it, and backend block agreement.

terminal
$ threatcl cloud validate -with='models/*.hcl' models/app-frontend.hcl

A preflight failure exits non-zero before any network call is made. See Multiple Files for the underlying set parsing rules.

Diffing a single segment

For one segment of a multi-file model, cloud validate -diff compares that file against its own segment in the cloud, shown in the diff header as cloud/<model>#<segment>, rather than against the model’s default segment. When the segment can’t be resolved, the diff is skipped with a warning instead of being run against the wrong baseline.