StrataCTL

StrataCTL is the local command-line tool for operators. It installs, updates, and removes StrataBI modules in your AWS account, installs the StrataBI platform itself, and version-controls your dashboards. You run it on your own machine with your own AWS credentials.

How it works

• You run it locally — a small Python CLI that uses your AWS credentials. It is not a hosted service.
• Module and platform installs run in your account. StrataCTL launches an ephemeral runner inside your AWS account that fetches the artifact, runs OpenTofu, writes state and logs into your own account, and exits. Your account owns the deployment state and logs end to end — nothing long-lived reaches in from outside. That runner and its supporting resources are StrataCI; see StrataCI — the execution plane for exactly what stratactl bootstrap provisions, how state is kept on an S3 backend, and how bundles are delivered.
• Dashboard sync talks to S3/DynamoDB directly (no runner needed).
• StrataCTL owns your deployment configuration. You answer questions; it writes the config and generates the Terraform/OpenTofu variable files. You do not hand-edit .tfvars.

Install

StrataCTL is on PyPI; install it with pipx (isolated, on your PATH):

pipx install stratactl
stratactl --help
stratactl --version

It's Apache-2.0 and open on GitHub — github.com/shaleio/stratactl. You'll also need OpenTofu 1.6+ (or Terraform) and AWS credentials for the target account. The Apache license covers the CLI only — it does not license StrataBI Enterprise, StrataHQ, or the SGCL-governed Developer Edition.

Installation wizard (stratactl init)

stratactl init is the recommended way to configure a deployment. It asks for the values an installation needs, saves them to a human-readable YAML config (strata.yaml, the source of truth), and generates the Terraform variable files from it.

stratactl init                 # configure a StrataBI deployment (interactive)
stratactl init module <id>     # configure an official module's variables
stratactl init --update        # re-prompt for every value, not just missing ones
stratactl init --non-interactive   # use saved config + defaults, no prompts (automation)

The wizard prompts only for values that are missing, validates inputs (region, VPC and subnet ids, CIDRs, image refs, ACM ARNs), and is safe to re-run — existing values are reused. It writes terraform.tfvars (into ./infra when present) and module variables into <module>.auto.tfvars. Generated files carry a "do not edit by hand" header: edit strata.yaml and re-run instead.

Example strata.yaml:

installation:
  name: production            # also the Terraform name_prefix
  aws_region: us-east-1
  organization: acme
  edition: enterprise
runtime:
  stratabi_image: 123456789012.dkr.ecr.us-east-1.amazonaws.com/stratabi:latest
network:
  vpc_id: vpc-0123abcd
  public_subnet_ids: [subnet-aaaa, subnet-bbbb]
  private_subnet_ids: [subnet-cccc, subnet-dddd]
  allowed_ip_cidrs: [203.0.113.0/24]
security:
  enable_guardduty: false
  enable_inspector: false
  enable_securityhub: false

Modules declare their own variables (an install.schema.json, or an install_schema block in module.json), so strata init module <id> prompts for them generically with no module-specific code in the CLI. The same strata.yaml is the configuration object future commands consume, so there is one source of truth across init, install, and update.

Installing modules

stratactl install <module> [--source customer_s3|stratahq] [--to <version>] [--env <env>]
stratactl update <module> [--to <version>] [--env <env>] [--reconfigure] [--allow-replace]
stratactl uninstall <module> [--env <env>]
stratactl list
stratactl logs <job-id>

install launches the runner, streams its logs to your terminal, and records the install. --source customer_s3 installs from your own S3 bucket; the default source can be set in config. update applies a new version; uninstall runs the module's destroy. list shows what's installed; logs <job-id> tails or replays a run.

Updates reuse the stored configuration. update does not re-read strata.yaml, so it behaves the same from any directory or machine. To change configuration during an update, pass --reconfigure. It re-reads strata.yaml, shows what would change, and asks before writing.

Every install and update runs two safety checks:

• Network preflight. Before launching, the CLI checks the environment's VPC and subnets against the account: they must exist, the subnets must belong to the VPC, and the public subnets must span two availability zones. This needs ec2:Describe*; without it the CLI warns and skips the check.
• Plan guard. The runner refuses to apply a plan that would destroy or replace protected infrastructure (VPC-bound security groups, the load balancer, the ECS cluster and service, buckets, tables, the Glue catalog, KMS keys, ECR, Cognito). It lists the affected resources and applies nothing. Re-run with --allow-replace only for a change you intend.

Environment config

The values that tie a deployment to your account's network and identity are stored once per environment, not per module:

s3://<strataci-bucket>/config/env/<env>.auto.tfvars.json
    name_prefix, region, vpc_id, public_subnet_ids, enable_private_subnets, private_subnet_ids

The first install seeds it from strata.yaml. After that, every module in the environment (the platform and every add-on module) reads the same values, and they take precedence over a module's own settings. <env> is the --env label every command takes (default dev). The StrataCI bucket is versioned, so any earlier version can be restored.

stratactl env show                     # print it
stratactl env set vpc_id=vpc-... public_subnet_ids=subnet-a,subnet-b
stratactl env import                   # read it from the deployed platform's state
stratactl env validate                 # check it against the account
stratactl env export --out zzz-env.auto.tfvars.json   # for a BYO CI/CD pipeline

set and import show the result, validate the network, and ask before writing (--yes skips the prompt).

Upgrading an install made before StrataCTL 1.7.8. Older installs have no environment config. update refuses until one exists, so that an upgrade can't pick up a different network. Run stratactl env import once (it reads the VPC and subnets from what's deployed), check the result with stratactl env show, then update.

Installing the platform

stratactl init                      # configure first (writes strata.yaml + tfvars)
stratactl install-stratabi          # commercial StrataBI Enterprise (licensed)
stratactl install-stratabi-dev      # StrataBI Developer Edition (HQ-free)

Run stratactl init first to collect configuration and generate the Terraform variables; then install. Both editions ship as bundles and install through the same runner path, so update, uninstall, list, and logs work on them too.

Developer Edition — which command? install-stratabi-dev and stratactl dev install perform the same install (the stratabi_dev bundle, no StrataHQ contract). Prefer the dev lifecycle group — dev install, dev configure-local, dev demo, dev uninstall — for the end-to-end Developer Edition workflow described in the Installation Guide and Developer Edition pages. install-stratabi-dev is the one-shot equivalent that mirrors install-stratabi.

Bring your own CI/CD (no CodeBuild)

For teams that deploy through their own pipeline, two commands expose the licensed artifacts without bootstrapping StrataCI or launching CodeBuild. Both run the same account-scoped, SigV4-signed entitlement check as an install; neither needs an in-account install plane. See Bring your own CI/CD for the end-to-end flow.

# resolve entitlement metadata (short-lived presigned URL + sha256 + signature) to a file
stratactl entitlement resolve --module stratabi --version 1.7.1 --output ./entitlement.json

# download + verify the signed OpenTofu bundle, ready for your own `tofu apply`
stratactl fetch-bundle --module stratabi --version 1.7.1 --output ./artifacts/module.zip

# build the image yourself for a customer-owned container supply chain
stratactl fetch-runtime --version 1.7.1 --dir ./build

These are additive — install-stratabi, install, update, uninstall, and the StrataCI runner are unchanged. Independently executed OpenTofu does not inherit the runner's state backend, module-scoped role, or account self-check; those become your pipeline's responsibility (see Bring your own CI/CD).

Dashboards

stratactl dashboards pull        # download git-registered dashboards locally
stratactl dashboards push        # deploy local dashboards back to S3
stratactl dashboards list
stratactl dashboards diff

This is the git side of the dashboards-as-code workflow — see Dashboards as code for the full picture, including the git button in the runtime and the overwrite-in-place model.

Configuration

StrataCTL resolves its settings from these layers, highest priority first:

1. a command-line flag,
2. an environment variable (STRATA_*),
3. a local config file (./.stratactl.toml, then ~/.stratactl/config.toml),
4. AWS SSM Parameter Store / Secrets Manager,
5. packaged defaults.

AWS credentials come from your normal AWS profile or keys (e.g. --profile, AWS_PROFILE, or environment credentials). Because the CLI acts as you, what you can install or deploy is governed by your own IAM permissions in the target account.