csw-tools

A collection of automation utilities for Cisco Secure Workload (CSW, formerly Tetration), available through a single command-line package.

Available Commands

Installation

The project requires Python 3.12 or later. uv is the preferred installation and development tool, although normal Python package installation also works.

Once uv is installed, install the package as a tool:

uv tool install csw-tools

Usage

List the available commands, common options, and project version information:

csw-tools --help
csw-tools --version

Global options must appear before the command name. The command and its own options follow:

csw-tools create-scopes scopes.csv
csw-tools --dashboard my-company.tetrationcloud.com prune-agents
csw-tools -d my-company configure-credentials

Command-generated files use csw-tools-outputs/ in the current working directory and a basic CLI log is enabled by default.

Every command's guide is linked from the tables above. The command help is the authoritative option list:

csw-tools COMMAND --help

CSW Dashboard Selection

A dashboard may be supplied as its short SaaS name, a full FQDN, or an HTTPS origin:

csw-tools -d my-company COMMAND
csw-tools -d my-company.tetrationcloud.com COMMAND
csw-tools -d mycsw.example.org COMMAND
csw-tools -d https://mycsw.example.org COMMAND

A short name is auto-appended by default with .tetrationcloud.com. Any FQDN is used as given with HTTPS. IP addresses and single-label on-premises hosts require HTTPS:// explicitly, such as -d https://192.0.2.10 or -d https://csw-local.

TLS certificate verification is enabled by default. Use --no-dashboard-verify-tls only for a trusted deployment whose certificate cannot be validated normally.

Configuration

Settings are resolved in this order:

1. CLI arguments
2. config.toml values
3. Backend defaults from config_defaults.py
4. Interactive prompt for an unresolved required value

config.toml is optional but useful for values that are reused often. Create or replace it interactively with:

csw-tools init

This copies the packaged config.example.toml to the OS-native per-user location:

• macOS: ~/Library/Application Support/csw-tools/config.toml
• Linux: ${XDG_CONFIG_HOME:-~/.config}/csw-tools/config.toml
• Windows: %APPDATA%\csw-tools\config.toml

If needed, use --config PATH before the command name to select a different file.

Credentials

Secrets are stored through the operating system keyring. For a dashboard named my-company, the default identifiers are:

Inspect/replace the credential pair with:

csw-tools -d my-company configure-credentials

(If using a CSW Dashboard that is not .tetrationcloud.com, then the full HTTPS url is used instead as part of the service name)

Safe Change Workflow

Most edit/write commands default to --dry-run; review the complete plan before using --apply. Supported commands create a timestamped JSON backup before the first API change in the common output directory and update it around each attempted operation.

Rollback support and limitations differ by command. Read the individual command guide before applying or recovering changes.

Development

See DEV-GUIDELINES.md for architecture, shared APIs, contributor workflow, and project checks.