CLI Reference - Tensor9

This is a complete reference for all tensor9 CLI commands. For installation instructions, see Install. For common workflows and examples, see Common Workflows.

Usage

tensor9 <command> [options]

Get help for any command:

tensor9 <command> -help
tensor9 help <command-group>

Authentication

Most commands require authentication via API key. Set your API key using the environment variable:

export T9_API_KEY=<your-api-key>

Alternatively, pass it as a parameter:

tensor9 <command> -apiKey <your-api-key>

Command Groups

The tensor9 CLI organizes commands into logical groups:

vendor: Vendor setup and management
app: Application management
stack: Stack and release management
form-factor: Form factor management
appliance: Customer appliance management
install: Listing app installs across appliances
Kubernetes: Kubernetes RBAC roles and EKS access
General commands: Help, update, install, report

General Commands

help

Display help information about available commands.

tensor9 help
tensor9 help <command-group>

Options:

-group (optional): Show help for a specific command group

Examples:

# Show all command groups
tensor9 help

# Show all vendor commands
tensor9 help vendor

# Show all stack commands
tensor9 help stack

env

Report on the current Tensor9 environment.

tensor9 env

Shows which Tensor9 stage you’re connected to (production, staging, etc.).

report

Generate a comprehensive report about your vendor account.

tensor9 report

Options:

-vendorId (optional): The vendor ID to report on (auto-discovered if not specified)
-detailed (optional): Produce a detailed report
-all (optional): Show all items instead of truncating lists
-outputFmt: Output format: Human (default), Json, Raw, Csv.
-raw: Output raw value only (alias for -outputFmt Raw).
-json: Output as JSON (alias for -outputFmt Json).
-csv: Output as CSV (alias for -outputFmt Csv).

Examples:

# Basic report
tensor9 report

# Detailed report
tensor9 report -detailed

The report displays:

Vendor details
All apps and their stacks
Customer appliances
Active releases

portal

Start a local web portal for managing your apps and appliances.

tensor9 portal

Options:

-vendorId (optional): The vendor ID (auto-discovered from API key if not specified)
-applianceName (optional): Appliance name if you have multiple appliances (Buyer)
-port (optional): Port to run the server on (default: 8080)
-noBrowser (optional): Don’t automatically open browser

Examples:

# Start portal on default port (8080) and open browser
tensor9 portal

# Use custom port
tensor9 portal -port 9090

# Start without opening browser
tensor9 portal -noBrowser

whoami

Display information about the currently authenticated user.

tensor9 whoami

Options:

-outputFmt: Output format: Human (default), Json, Raw, Csv.
-raw: Output raw value only (alias for -outputFmt Raw).
-json: Output as JSON (alias for -outputFmt Json).
-csv: Output as CSV (alias for -outputFmt Csv).

Vendor Commands

vendor setup

Set up Tensor9 in your AWS account. This creates your control plane for managing customer appliances.

tensor9 vendor setup [options]

Options:

-region (optional): The cloud region. Auto-detected if not provided.
-awsProfile (optional): AWS profile to use for credentials.
-vendorId (optional): The vendor ID to set up Tensor9 for (auto-discovered if not specified)
-force (optional): Force setup to proceed even if it would overwrite existing resources

Examples:

# Interactive setup (prompts for all inputs)
tensor9 vendor setup

# Non-interactive AWS setup
tensor9 vendor setup \
  -region us-west-2 \
  -awsProfile my-profile

Your Tensor9 AWS account should be a dedicated AWS account used only for Tensor9. This reduces the risk of conflicts with other infrastructure.

vendor report

Generate a detailed report of the vendor’s resources.

tensor9 vendor report [options]

Options:

-vendorId (optional): The vendor ID to report on. Auto-discovered if not specified.
-detailed (optional): Produce a detailed report.
-all (optional): Show all items instead of truncating lists.

vendor upgrade

Upgrade your Tensor9 vendor infrastructure or control-plane software. Use Infrastructure to re-apply the Tensor9 Terraform modules against your AWS account, or Software to deploy the latest control-plane software to your VCtrl instance.

tensor9 vendor upgrade -reason <reason> [options]

Required:

-reason: Operator note describing the motivation for this upgrade.

Optional:

-kind: Upgrade kind. One of Infrastructure (default) or Software.
-region: AWS region. Auto-detected if not provided.
-awsProfile: AWS profile to use for credentials.
-vendorId: Vendor ID. Auto-discovered from API key if not specified.
-targetDefId: Specific upgrade definition to target (e.g., fabric-2026.04.24). Defaults to the latest registered definition for the chosen kind.

Examples:

# Re-apply infrastructure modules (default kind)
tensor9 vendor upgrade -reason "pick up new fabric module"

# Upgrade control-plane software only
tensor9 vendor upgrade \
  -kind Software \
  -reason "deploy latest control plane"

# Pin to a specific upgrade definition
tensor9 vendor upgrade \
  -kind Infrastructure \
  -reason "rollout new VPC layout" \
  -targetDefId fabric-2026.04.24

A vendor upgrade holds a 5-minute lease while running. If a previous upgrade was interrupted, wait for the lease to expire before retrying.

App Commands

app create

Create a new app.

tensor9 app create -name <name> -displayName <display-name> [options]

Required:

-name: The app name (alphanumeric, underscores, hyphens; 3-64 characters)
-displayName: A friendly name for the app.

Optional:

-stackType: The type of stack to bind to the app. Must be one of: CloudFormation, Terraform, TerraformWorkspace, DockerContainer, DockerCompose, Helm.
-nativeStackId: The native id of the stack to bind to the app (e.g. arn:aws:cloudformation:us-west-2:1234:stack/my-stack/abcd for CloudFormation).
-vanityDomain: A custom vanity domain name for this app. This is used to create endpoints used by your app, including per-appliance endpoints for appliances that install your app. e.g. any-prem.vendor.co.
-json: Output as JSON instead of human-readable text.

Examples:

# Create app without binding a stack
tensor9 app create \
  -name my-app \
  -displayName "My Application"

# Create app and bind Docker Compose stack
tensor9 app create \
  -name my-app \
  -displayName "My Application" \
  -stackType DockerCompose \
  -nativeStackId "s3://t9-ctrl-000001/my-app-compose.yml"

# Create app with vanity domain
tensor9 app create \
  -name my-app \
  -displayName "My Application" \
  -vanityDomain anyprem.mycompany.com

Generate a signup link for customers to sign up for your app.

tensor9 app signup-link -appName <app-name>

Required (one of):

-appId: The app ID
-appName: The app name

Examples:

# Generate signup link by app name
tensor9 app signup-link -appName my-app

# Generate signup link by app ID
tensor9 app signup-link -appId 0000000000000123

Returns a URL like https://portal.tensor9.com/buyerSignup?appId=... that you can send to customers.

app list

List applications by vendor.

tensor9 app list [options]

Options:

-outputFmt: Output format: Human (default), Json, Raw, Csv.
-raw: Output raw value only (alias for -outputFmt Raw).
-json: Output as JSON (alias for -outputFmt Json).
-csv: Output as CSV (alias for -outputFmt Csv).

app retrieve

Retrieve application details.

tensor9 app retrieve -appId <id>

Required:

-appId: The ID of the app to retrieve.

Stack Commands

stack publish

Upload a stack definition to your control plane.

tensor9 stack publish \
  -appName <app-name> \
  -stackType <type> \
  -stackS3Key <key> \
  [options]

Required:

-appName: The name of the app to upload the stack for.
-stackS3Key: The name for the stack archive (without file extension).
-stackType: The type of stack. Must be one of: CloudFormation, Terraform, TerraformJson, Kube, TerraformWorkspace, DockerContainer, DockerCompose, Helm.

Optional:

-dir: For TerraformWorkspace: The directory containing .tf files. Defaults to the current directory.
-file: For DockerCompose: The path to the docker-compose.yml file. (For TerraformWorkspace, use -dir instead).

Examples:

# Publish Terraform stack
tensor9 stack publish \
  -appName my-app \
  -stackType TerraformWorkspace \
  -stackS3Key my-app-stack \
  -dir ./terraform

# Publish Docker Compose stack
tensor9 stack publish \
  -appName my-app \
  -stackType DockerCompose \
  -stackS3Key my-app-compose \
  -file docker-compose.yml

Returns a native stack ID like s3://t9-ctrl-000001/my-app-stack.tf.tgz.

stack bind

Bind an origin stack (e.g., CloudFormation, Terraform, Docker, etc.) to your app.

tensor9 stack bind \
  -stackType <type> \
  [options]

Required:

-stackType: The type of stack to bind. Must be one of: CloudFormation, Terraform, TerraformJson, Kube, TerraformWorkspace, DockerContainer, DockerCompose, Helm.
Note: You must provide either -nativeStackId or -gitHubUrl.

Optional:

-appName: The name of the app to bind the stack to.
-appVersion: The version of the app to bind to (defaults to latest).
-stackName: A friendly name for the stack being bound.
-nativeStackId: The native ID of the stack.
- TerraformWorkspace: s3://my-bucket/my-stack.tf.tgz
- DockerContainer: 123456789012.dkr.ecr.us-west-2.amazonaws.com/my-container:latest
- CloudFormation: arn:aws:cloudformation:us-west-2:0011223344556677:stack/my-stack/...
-gitHubUrl: A GitHub URL pointing to a directory containing Terraform files (mutually exclusive with -nativeStackId).
-subPath: For -gitHubUrl with TerraformWorkspace: the subdirectory within the checkout containing the root module (main.tf).
-credentialType: The type of credential to use for cross-account or cross-cloud access. (e.g., AwsRoleArn, GcpTrustedServiceAccountEmail, GitHubUserAndToken, DigitalOceanToken, etc.)
-credential: The credential value.

Examples:

# Bind Terraform stack via S3
tensor9 stack bind \
  -appName my-app \
  -stackType TerraformWorkspace \
  -nativeStackId "s3://t9-ctrl-000001/my-app-stack.tf.tgz"

# Bind Terraform stack via GitHub
tensor9 stack bind \
  -appName my-app \
  -stackType TerraformWorkspace \
  -gitHubUrl "https://github.com/owner/repo/tree/main/terraform"

# Bind CloudFormation stack
tensor9 stack bind \
  -appName my-app \
  -stackType CloudFormation \
  -nativeStackId "arn:aws:cloudformation:us-west-2:123456789012:stack/my-stack/..."

You only need to bind once per app. Future publishes of the same stack don’t require re-binding.

stack unbind

Unbind an origin stack (e.g., CloudFormation stack) from your app.

tensor9 stack unbind [options]

Required (one of):

-appName: The name of the app to unbind from.
-appId: The ID of the app to unbind from.

Required (one of):

-stackId: The Tensor9 stack ID (found in tensor9 report).
-stackName: The friendly name of the stack to unbind.
Note: If neither is specified and only one stack is bound to the app, that stack will be automatically targeted.

Examples:

# Unbind by app name (if only one stack bound)
tensor9 stack unbind -appName my-app

# Unbind specific stack by friendly name
tensor9 stack unbind -appName my-app -stackName my-main-stack

# Unbind specific stack by ID
tensor9 stack unbind -appId 0000000000000123 -stackId 0000000000000456

stack release create

Release a stack to one or more appliances.

tensor9 stack release create [options]

Options:

-appName: The name of the app to release.
-vendorVersion: Version string (e.g., v5.4.0).
-description: A short description of the release.
-notes: A description of the release (detailed notes).

Target (exactly one required):

-projectionIds: The IDs of the projections to release to. Must be JSON-encoded as a list of strings (e.g., ["0000000000000001:9a961d63e1120abe:0e4348b322904268", "0000000000000001:230d826ab554c3e7:6a40a3b5d3c807a5"]).
-testAppliance or -testApplianceName: The name of a test appliance to use for this release.
-customerName or -buyerName: The name of the customer to release to.
-all: Release to all appliances.

Optional:

-stackId or -stackName: Required if the app has multiple stacks bound to it.
-tuningDoc: A file containing the tuning document for this release.
-tuningDocFmt: The format of the tuning document file: Json, Yaml. (Defaults to Json).

Examples:

# Release to specific projections
tensor9 stack release create \
  -appName my-app \
  -projectionIds '["0000000000000001:9a961d63e1120abe:0e4348b322904268"]' \
  -vendorVersion "v5.4.0" \
  -description "Hotfix" \
  -notes "Detailed notes here"

# Release to customer
tensor9 stack release create \
  -appName my-app \
  -customerName acme-corp \
  -vendorVersion "v5.4.0" \
  -description "Initial release" \
  -notes "Production-ready version"

# Release to test appliance
tensor9 stack release create \
  -appName my-app \
  -testApplianceName my-test-appliance \
  -vendorVersion "v5.4.0" \
  -description "Testing" \
  -notes "Internal verification"

After creating a release, the deployment stack downloads to a directory named after the appliance. Deploy it using:

cd <appliance-name>
terraform init
terraform apply

stack release retire

Retire a release of an app.

tensor9 stack release retire [options]

Options:

-releaseId: The ID of the release to retire.
OR:
- -vendorVersion: The vendor version of the release to retire.
- -appName: The name of the app to retire a release for.

Filters (apply when using -vendorVersion and -appName):

-stackName: The name of the stack to retire releases for.
-customerName or -buyerName: The name of the customer to retire a release for.
-reason: The reason for retiring the release.

Examples:

# Retire by release ID
tensor9 stack release retire -releaseId 0000000000000789

# Retire by version
tensor9 stack release retire \
  -appName my-app \
  -vendorVersion "v5.4.0" \
  -customerName acme-corp \
  -reason "Security vulnerability fixed in v5.4.1"

stack list

List stack definitions for a vendor.

tensor9 stack list -vendorId <id>

Required:

-vendorId: The vendor ID.

stack retrieve

Retrieve a specific stack definition.

tensor9 stack retrieve -vendorId <id> -stackId <id>

Required:

-vendorId: The vendor ID.
-stackId: The stack ID to retrieve.

stack release list

List stack releases for an app.

tensor9 stack release list [options]

Required (one of):

-appName: App name to list releases for.
-appId: App ID to list releases for.

Options:

-outputFmt: Output format: Human (default), Json, Raw, Csv.
-raw: Output raw value only (alias for -outputFmt Raw).
-json: Output as JSON (alias for -outputFmt Json).
-csv: Output as CSV (alias for -outputFmt Csv).

stack release download

Download released stacks for one or more appliances.

tensor9 stack release download -appName <name> -vendorVersion <version> [options]

Required:

-appName: The name of the app to download the release for.
-vendorVersion: The vendor version to download (e.g., v5.4.0). Use -latest to download the most recent release.

Optional:

-stackId: The stack ID to download. Required if the app has multiple stacks bound to it.
-outDir: The directory to download the stack(s) to. Defaults to the current directory.
-historyRetention: Number of previous release snapshots to keep in .tensor9/history/. Defaults to 10.

Examples:

# Download the latest release for an app
tensor9 stack release download \
  -appName my-app \
  -vendorVersion -latest

# Download a specific version to a custom directory
tensor9 stack release download \
  -appName my-app \
  -vendorVersion v5.4.0 \
  -outDir ./releases

# Multi-stack app: specify which stack to download
tensor9 stack release download \
  -appName my-app \
  -stackId 0000000000000456 \
  -vendorVersion v5.4.0

The download creates a directory per appliance containing the deployment stack. Deploy it with the appropriate IaC tool:

cd <appliance-name>
tofu init
tofu apply

stack release-pending list

List pending stack releases.

tensor9 stack release-pending list -vendorId <id> -appId <id>

Required:

-vendorId: The vendor ID.
-appId: App ID to filter pending releases.

stack release-bundle download

Download a release bundle.

tensor9 stack release-bundle download -releaseId <id> -projectionId <id> -outputFile <path>

Required:

-releaseId: The release ID to download.
-projectionId: The projection ID.
-outputFile: Path to save the downloaded bundle.

stack release-bundle apply

Apply a release bundle manually from a local file or presigned URL.

tensor9 stack release-bundle apply -releaseBundleFmt <format> -bxEndpoint <endpoint> [options]

Required:

-releaseBundleFmt: Format (e.g., Tgz_2024_12_07).
-bxEndpoint: Coordinator endpoint to use.

Required (exactly one of):

-releaseBundleFile: Path to the bundle file.
-releaseBundleUrl: Presigned URL for air-gapped deployments.

Terraform Commands

tf import

Import or adopt an existing resource into Tensor9 management. This command handles two scenarios:

State recovery — You lost your local Terraform state (e.g., crash, environment rebuild). The resource was previously deployed through Tensor9. Running tf import recovers your local state.
Resource adoption — A deployment failed because the resource already exists (e.g., “BucketAlreadyOwnedByYou”, “resource already exists”). Running tf import --nativeId tells Tensor9 to adopt the existing resource instead of trying to create a new one.

tensor9 tf import \
  --customerName <name> \
  --version <version> \
  --resource <resource> \
  [--nativeId <resource-id>] \
  [--stackName <stack-name>] \
  [options]

Required:

--version: Vendor version of the release (e.g., 1.0.0)
--resource: The twin resource name from your compiled stack, optionally module-qualified (e.g., aws_s3_bucket_main_twin, module.vpc.aws_s3_bucket_main_twin)

Scope (exactly one required):

--customerName: Customer name (e.g., acme-corp)
--customerId: Customer ID
--applianceName: Appliance name
--applianceId: Appliance ID
--installationId: Installation ID (most specific — use when other scopes are ambiguous)

Optional:

--nativeId: The resource’s import ID. Required when a deployment failed because the resource already exists. The format depends on the resource type — see Terraform provider docs for the expected format.
--stackName: Stack name to disambiguate when multiple stacks contain a resource with the same name
--dir: Directory containing your Terraform configuration (defaults to current directory)
--tfBin: Path to the tofu/terraform binary (auto-discovered by default)

Examples:

# Recover local state after losing terraform.tfstate
tensor9 tf import \
  --customerName acme-corp \
  --version 1.0.0 \
  --resource aws_s3_bucket_main_twin

# Adopt an existing S3 bucket after a failed deployment
tensor9 tf import \
  --customerName acme-corp \
  --version 1.0.0 \
  --resource aws_s3_bucket_main_twin \
  --nativeId my-existing-bucket

# Adopt with module-qualified resource
tensor9 tf import \
  --customerName acme-corp \
  --version 1.0.0 \
  --resource module.vpc.aws_subnet_main_twin \
  --nativeId subnet-0123456789abcdef0

# Multi-stack app — specify which stack
tensor9 tf import \
  --customerName acme-corp \
  --version 1.0.0 \
  --resource aws_s3_bucket_main_twin \
  --nativeId my-existing-bucket \
  --stackName my-vpc-stack

What is --nativeId? It’s the value you would pass to tofu import for this resource type. The format varies by resource:

aws_s3_bucket — bucket name (e.g., my-bucket)
aws_instance — instance ID (e.g., i-1234567890abcdef0)
aws_lb — ARN (e.g., arn:aws:elasticloadbalancing:...)
aws_ecs_service — cluster-name/service-name

Check the “Import” section in your Terraform provider docs for the expected format.

After adopting a resource, run tofu apply to reconcile your deployment. This applies any configuration differences (such as tags) between your stack definition and the existing resource.

Form Factor Commands

svc-spec-doc template generate

Generate a service specification document by analyzing your app’s bound stacks and mapping discovered services to target environment equivalents.

tensor9 svc-spec-doc template generate \
  -appName <app-name> \
  -targetEnv <environment> \
  [options]

Required:

-appName: The app name (must have Terraform stacks bound)
-targetEnv: Customer environment (Aws, Gcp, Azure, DigitalOcean, Kube, Metal, BareMetal)

Optional:

-output: Output file path. Use - or omit for stdout.

This command:

Analyzes Terraform stacks bound to your app
Discovers AWS services (EKS, RDS, VPC, etc.)
Maps each service to its target environment equivalent
Generates a service specification document with dependencies and version constraints

Examples:

# Generate spec for Kubernetes target
tensor9 svc-spec-doc template generate \
  -appName my-app \
  -targetEnv Kube \
  -output config.json

When multiple target options exist for a service, you’ll be prompted to select which to offer customers:

Loading App 'my-app'...
Generating service specs for Kube...

Discovered 3 AWS service(s):
  - aws::1.0.0::eks::cluster (v1.29)
  - aws::1.0.0::rds::postgresql (v14.0)
  - aws::1.0.0::iam

1 service(s) have multiple target candidates.
Select which options to offer customers (1 selection = Exact, 2+ = OneOf):

aws::1.0.0::rds::postgresql → select target service(s):
  [x] cloudnative::1.0.0::postgresql
  [ ] gcp::1.0.0::cloudsql::postgresql

  Generated Exact for aws::1.0.0::rds::postgresql

Generated 3 spec(s)
  - kubernetes::1.0.0::cluster
  - cloudnative::1.0.0::postgresql
  - tensor9::1.0.0::iam

Config written to: config.json

Next step - create form factor:
  tensor9 form-factor create \
    -appName my-app \
    -formFactorName kube-connected \
    -env Kube \
    -connectivity Connected \
    -svcSpecDoc config.json

Selecting multiple options creates a OneOf requirement, letting customers choose their preferred service equivalent.

After generating the service specification document, review the tuning fields for each service. Since scaling requirements for private deployments often differ from your cloud deployment, this is an opportunity to tune resource allocations (storage size, replicas, CPU, memory) for the specific form factor.

form-factor create

Create a new form factor for your app (e.g., aws-connected, digitalocean-connected).

tensor9 form-factor create \
  -appName <app-name> \
  -formFactorName <name> \
  -env <environment> \
  -connectivity <mode> \
  [options]

Required:

-appName: The name of the app to create a form factor for.
-formFactorName: A name for the form factor (must match: [a-z0-9_\-]{1,64}).
-env: The environment for the form factor. One of: Aws, Gcp, Azure, DigitalOcean, Kube, Metal, Local, BareMetal.
-connectivity: The connectivity for the form factor. One of: Connected, Disconnected, AirGapped.

Optional:

-description: A description for the form factor.
-svcSpecDoc: Path to JSON file containing service specification documents. Use svc-spec-doc template generate to generate a starter file.

Examples:

# Create AWS connected form factor
tensor9 form-factor create \
  -appName my-app \
  -formFactorName aws-connected \
  -description "AWS with internet connectivity" \
  -env Aws \
  -connectivity Connected

# Create form factor with service specifications
tensor9 form-factor create \
  -appName my-app \
  -formFactorName kube-connected \
  -env Kube \
  -connectivity Connected \
  -svcSpecDoc config.json

form-factor export

Export an existing form factor as SvcSpecDoc JSON for modification and evolution.

tensor9 form-factor export \
  -appName <app-name> \
  -formFactorName <name> \
  [options]

Required:

-appName: The name of the app that owns the form factor.
-formFactorName: The name of the form factor to export.

Optional:

-version: Specific version to export (e.g., 1.2.0). Defaults to current (latest) version.
-output: Output file path. Use - or omit for stdout.

This command retrieves a form factor and converts it to the same SvcSpecDoc format used by form-factor create. The exported JSON can be modified and then used with form-factor evolve to create a new version. The export includes:

Service requirements (Exact and OneOf)
Service tunings (converted to tuning JSON)
Service dependency requirements

env and connectivity are not included in the SvcSpecDoc as they cannot be changed during evolution. The export includes these as informational comments in the output.

Examples:

# Export current (latest) version to stdout
tensor9 form-factor export -appName my-app -formFactorName aws-connected

# Export specific version to file
tensor9 form-factor export -appName my-app -formFactorName aws-connected -version 1.2.0 -output config.json

After exporting, edit the JSON and use it to evolve the form factor:

tensor9 form-factor evolve -appName my-app -formFactorName aws-connected -svcSpecDoc config.json

form-factor promote

Promote a form factor version to Preferred status.

tensor9 form-factor promote \
  -appName <app-name> \
  -formFactorName <name> \
  -version <version>

Required:

-appName: The name of the app that owns the form factor.
-formFactorName: The name of the form factor.
-version: The version to promote (e.g., 1.2.0).

The promoted version becomes the default for new projections. The previously Preferred version is automatically demoted to Active. Examples:

tensor9 form-factor promote -appName my-app -formFactorName aws-connected -version 1.2.0

form-factor retire

Retire a form factor version.

tensor9 form-factor retire \
  -appName <app-name> \
  -formFactorName <name> \
  -version <version>

Required:

-appName: The name of the app that owns the form factor.
-formFactorName: The name of the form factor.
-version: The version to retire (e.g., 1.0.0).

Retired versions cannot serve new projections, and existing projections using a retired version should be upgraded. Note: The Preferred version cannot be retired; you must promote another version first. Examples:

tensor9 form-factor retire -appName my-app -formFactorName aws-connected -version 1.0.0

form-factor evolve

Evolve an existing form factor to a new version using a modified SvcSpecDoc.

tensor9 form-factor evolve \
  -appName <app-name> \
  -formFactorName <name> \
  -svcSpecDoc <path> \
  [options]

Required:

-appName: The name of the app that owns the form factor.
-formFactorName: The name of the form factor to evolve.
-svcSpecDoc: Path to the SvcSpecDoc JSON file (typically generated via form-factor export) with updated service requirements.

Optional:

-name: New name for the form factor (defaults to current name).
-description: New description for the form factor (defaults to current description).

This command creates a new version of the form factor. The version bump (Major, Minor, or Patch) is automatically detected based on the changes:

Major: Breaking changes (e.g., stricter constraints, new requirements, removed choices).
Minor: Compatible additions (e.g., relaxed constraints, new choices, removed requirements).
Patch: Metadata changes only (e.g., name or description updates).

env and connectivity cannot be changed during evolution. Changing these requires creating a new form factor instead.

Examples:

# Evolve with updated configuration
tensor9 form-factor evolve -appName my-app -formFactorName aws-connected -svcSpecDoc config.json

# Evolve with new name and description
tensor9 form-factor evolve \
  -appName my-app \
  -formFactorName aws-connected \
  -svcSpecDoc config.json \
  -name "aws-connected-v2" \
  -description "Updated for Kubernetes 1.30"

Typical Workflow:

Export: tensor9 form-factor export -appName my-app -formFactorName aws-connected -output config.json
Edit: Modify config.json with updated service requirements or tunings.
Evolve: tensor9 form-factor evolve -appName my-app -formFactorName aws-connected -svcSpecDoc config.json

form-factor version lifecycle

When you evolve a form factor, the new version starts as Active. Existing installs stay pinned to their original version until explicitly upgraded. See Form factor versioning for details on version statuses (Preferred, Active, Retiring, Retired).

service specification document format

The service specification document is a JSON file used with form-factor create and form-factor evolve to define service requirements and dependencies.

{
  "services": [
    {
      "svcId": "cloudnative::1.0.0::postgresql|abc123",
      "versionConstraints": ">=14.0.0",
      "tuning": {
        "overrideAllocatedStorageInGib": 100,
        "overrideNumReplica": 2,
        "overrideVCpu": 4,
        "overrideMemoryInGib": 8
      },
      "origin": "aws:tf:my-app-stack@module::database|aws_db_instance.main"
    }
  ],
  "dependencies": [
    {
      "name": "cloudnative::1.0.0::cnpg::operator",
      "versionConstraints": ">=1.24.0",
      "installMethod": "Managed"
    }
  ]
}

Services can be specified in two modes (see Service requirements): Exact mode - A single, specific service requirement:

{
  "svcId": "cloudnative::1.0.0::postgresql|abc123",
  "versionConstraints": ">=14.0.0",
  "tuning": {
    "overrideAllocatedStorageInGib": 100
  },
  "origin": "aws:tf:my-app-stack@module::database|aws_db_instance.main"
}

OneOf mode - Customer chooses from multiple options:

{
  "choices": [
    {
      "svcId": "cloudnative::1.0.0::postgresql|abc123",
      "versionConstraints": ">=14.0.0",
      "tuning": {
        "overrideAllocatedStorageInGib": 100
      }
    },
    {
      "svcId": "byo::1.0.0::postgresql|def456",
      "versionConstraints": ">=14.0.0"
    }
  ],
  "origin": "aws:tf:my-app-stack@module::database|aws_db_instance.main"
}

Dependencies are infrastructure components (like Helm charts or operators) that service equivalents may require. You specify which versions are acceptable using semver constraints, and Tensor9 installs the latest version that satisfies the constraint.

name: The dependency identifier
versionConstraints: Semver constraint you specify (e.g., >=1.24.0, >=1.24.0 <2.0.0)
installMethod: Either Managed (Tensor9 installs it) or PreInstalled (customer already has it). Note: private Kubernetes environments only support PreInstalled.

Tensor9 manages dependencies using reference counting to ensure they’re installed exactly once and cleaned up when no longer needed.

Appliance Setup Commands

appliance setup create

Create a setup script that can be used to set up an appliance.

tensor9 appliance setup create \
  -customerName <customer> \
  -appName <app> \
  -cloud <cloud> \
  -formFactorName <form-factor>

Required:

-customerName: The name of the customer that will own the appliance.
-appName: The name of the app to be installed into that appliance.
-cloud: The cloud to set up the appliance in: Aws, Gcp, Azure, Private, Local.
-formFactorName: The name of the form factor the appliance will have.

Optional:

-privateCloudName: The name of the private cloud the appliance will be in. Must be owned by the same customer that will own the appliance.
-vendorMetadata: JSON-encoded map of string key/value pairs to set on the resulting install once the appliance is set up and the app is installed.

Examples:

# Create AWS setup script
tensor9 appliance setup create \
  -customerName acme-corp \
  -appName my-app \
  -cloud Aws \
  -formFactorName aws-connected

# Create setup script with metadata
tensor9 appliance setup create \
  -customerName acme-corp \
  -appName my-app \
  -cloud Gcp \
  -formFactorName gcp-connected \
  -vendorMetadata '{"tier":"enterprise","region":"us"}'

Returns a setup key and instructions to send to your customer.

appliance setup list

List appliance setups.

tensor9 appliance setup list -appId <id>

Optional:

-appId: The ID of the app to list appliance setups for.
-buyerId: The ID of the customer to list appliance setups for.

appliance setup retrieve

Retrieve appliance setup info.

tensor9 appliance setup retrieve -applianceSetupKey <key>

Required:

-applianceSetupKey: The appliance setup key of the appliance setup to retrieve.

Appliance Commands

appliance list

List all appliances.

tensor9 appliance list

Optional:

-outputFmt: Output format: Human (default), Json, Raw, Csv.
-raw: Output raw value only (alias for -outputFmt Raw).
-json: Output as JSON (alias for -outputFmt Json).
-csv: Output as CSV (alias for -outputFmt Csv).

appliance retrieve

Retrieve appliance details.

tensor9 appliance retrieve -applianceName <name> -customerName <customer>

You must specify either:

-applianceName + -customerName: Retrieve by appliance name.
-applianceId: Retrieve by appliance ID.

Optional:

-applianceName: The name of the appliance to retrieve. Requires -customerName. Alternative: use -applianceId.
-customerName: The name of the customer that owns the appliance. Required with -applianceName.
-applianceId: The ID of the appliance to retrieve. Alternative: use -applianceName with -customerName.
-outputFmt: Output format: Human (default), Json, Raw, Csv.
-raw: Output raw value only (alias for -outputFmt Raw).
-json: Output as JSON (alias for -outputFmt Json).
-csv: Output as CSV (alias for -outputFmt Csv).

appliance check

Health check an appliance.

tensor9 appliance check -applianceId <id>

Required:

-applianceId: The appliance ID of the appliance to health check.

Install Commands

install list

List installs across apps, customers, or appliances. An install represents one of your apps running on a specific customer’s appliance.

tensor9 install list [options]

Filter (exactly one required):

-appName: List all installs for an app. Alternative: -appId.
-customerName: List all installs for a customer. Alternative: -customerId.
-applianceName: List installs on a specific appliance. Requires -customerName. Alternative: -applianceId.

Examples:

# List all installs of an app across all customers
tensor9 install list -appName my-app

# List all installs for a customer
tensor9 install list -customerName acme

# List installs on a specific appliance
tensor9 install list \
  -applianceName acme-prod \
  -customerName acme

Kubernetes Commands

kube role list

List Tensor9 Kubernetes RBAC roles and their default state. Prints the kubectl commands to check current bindings on the cluster. Run by the customer using a customer API key.

tensor9 kube role list [options]

Optional:

-applianceName: Appliance name (required if the customer has multiple appliances).
-namespace: Override namespace (auto-discovered from appliance configuration).
-clusterWide: Use ClusterRoleBinding scope instead of namespace-scoped RoleBinding.

The command lists 6 RBAC roles and their default state:

Role	Default	Description
`install`	disabled	Full infrastructure provisioning. Required for Tensor9 to perform infrastructure provisioning and upgrades.
`steady-state`	enabled	Read-only monitoring. Required for Tensor9 to monitor appliance health.
`deploy`	disabled	Create or modify vendor workloads
`operate-readonly`	disabled	Read-only troubleshooting
`operate-readwrite`	disabled	Write troubleshooting
`operate-admin`	disabled	Full troubleshooting

Examples:

# List roles for a single-appliance customer
tensor9 kube role list

# List roles for a specific appliance
tensor9 kube role list -applianceName my-appliance

# List roles using cluster-wide scope
tensor9 kube role list -clusterWide

kube role enable

Print the kubectl apply command needed to enable a Tensor9 RBAC role. This command does not mutate the cluster; it prints the command that the customer must run to apply the binding.

tensor9 kube role enable -role <role> [options]

Required:

-role: The role to enable. One of: install, steady-state, deploy, operate-readonly, operate-readwrite, operate-admin.

Optional:

-applianceName: Appliance name (required if multiple appliances).
-namespace: Override namespace (auto-discovered).
-clusterWide: Generate a ClusterRoleBinding instead of a namespace-scoped RoleBinding.

Examples:

# Print the apply command for the deploy role
tensor9 kube role enable -role deploy

# Print the apply command for cluster-wide admin access
tensor9 kube role enable -role operate-admin -clusterWide

kube role disable

Print the kubectl delete command needed to disable a Tensor9 RBAC role. This command does not mutate the cluster; it prints the command that the customer must run to remove the binding.

tensor9 kube role disable -role <role> [options]

Required:

-role: The role to disable. One of: install, steady-state, deploy, operate-readonly, operate-readwrite, operate-admin.

Optional:

-applianceName: Appliance name (required if multiple appliances).
-namespace: Override namespace (auto-discovered).
-clusterWide: Target a ClusterRoleBinding instead of a namespace-scoped RoleBinding.

Disabling steady-state prevents Tensor9 from monitoring the appliance’s health. Disabling install prevents Tensor9 from performing infrastructure provisioning and upgrades.

Examples:

tensor9 kube role disable -role deploy
tensor9 kube role disable -role operate-admin -clusterWide

aws eks grant-access

Grant an IAM role full admin access to an EKS cluster. This command mutates the cluster: it creates an access entry, associates AmazonEKSClusterAdminPolicy, and updates the local kubeconfig.

tensor9 aws eks grant-access -clusterName <name> -roleArn <arn> [options]

Required:

-clusterName: The EKS cluster name.
-roleArn: The full IAM role ARN to grant access to (e.g., arn:aws:iam::123456789012:role/MyRole).

Optional:

-region: AWS region. Defaults to us-west-2.
-awsProfile: AWS profile to use for credentials.
-skipKubeconfig: Skip the local kubeconfig update step.

The command performs four steps:

Ensures the cluster’s authentication mode is API_AND_CONFIG_MAP.
Creates an access entry for the IAM role.
Associates the AmazonEKSClusterAdminPolicy with the access entry.
Updates the local kubeconfig to point at the cluster (unless -skipKubeconfig is set).

Examples:

# Grant access in the default region with the default AWS profile
tensor9 aws eks grant-access \
  -clusterName my-cluster \
  -roleArn arn:aws:iam::123456789012:role/MyRole

# Grant access in a specific region
tensor9 aws eks grant-access \
  -clusterName my-cluster \
  -roleArn arn:aws:iam::123456789012:role/MyRole \
  -region us-east-1

# Skip the kubeconfig update
tensor9 aws eks grant-access \
  -clusterName my-cluster \
  -roleArn arn:aws:iam::123456789012:role/MyRole \
  -skipKubeconfig

Advanced Commands

appliance setup

Set up an appliance (run by customer in their environment).

tensor9 appliance setup \
  -setupKey <key> \
  -cloudRegion <region> [options]

Required:

-setupKey: A single-use setup key identifying which appliance is being set up and how to set it up.
-cloudRegion: Cloud region (e.g., aws:us-west-2, gcp:us-central1).

Optional:

-autoApprove: Automatically approve infrastructure changes. Required for non-interactive setups.
-vanityDomain: The vanity domain for the appliance (e.g., app-name.company.com).
-domainSuffix: Domain suffix for the appliance (e.g., app-name.internal.company.com).
-privateZone: Whether the domain suffix should be a private zone instead of a public zone.
-gcpProjectId: The project ID of the GCP project the appliance will live in. Only applies if setting up an appliance in GCP. Defaults to the project ID of the GCP environment running this action (if any).
-resourceTags: JSON-encoded key/value pairs to apply as tags on all cloud resources created by the appliance.
-credentialType: The type of credential to use to set up your appliance. Must be paired with -credential.
-credential: The credential to use to set up your appliance. Must be paired with -credentialType.
-buyerSvcSpec: Path to a service spec JSON file containing service selections and configurations. When provided, the setup record is updated with customer inputs before proceeding with setup.
-json: Output the created appliance as JSON instead of human-readable text.
-kubeClusterMode: Kubernetes cluster mode for Kube form factors: DedicatedCluster or VCluster.
-kubeCfg: Path to kubeconfig file for Kube form factors.
-vClusterName: vCluster name (required when kubeClusterMode=VCluster).
-vClusterHostNamespace: Host namespace for vCluster (required when kubeClusterMode=VCluster).

Examples:

# Interactive AWS setup
tensor9 appliance setup \
  -setupKey abc123... \
  -cloudRegion aws:us-west-2

# Non-interactive GCP setup
tensor9 appliance setup \
  -setupKey abc123... \
  -cloudRegion gcp:us-central1 \
  -gcpProjectId my-project \
  -autoApprove \
  -resourceTags '{"environment":"production"}'

machine setup

Set up a machine in a private cloud.

tensor9 machine setup \
  -type <type> \
  -ip <ip-address> [options]

Required:

-type: Machine type (Ctrl or Iso)
-ip: IP address exposed to other machines in the private cloud

Optional:

-zone: Zone name (e.g., datacenter-1)
-gpu: GPU type (None, NvidiaT4, NvidiaA10, NvidiaA100, etc.)
-force: Force setup even if already set up

Examples:

# Set up control machine
tensor9 machine setup \
  -type Ctrl \
  -ip 10.0.1.10 \
  -zone datacenter-1

# Set up isolated machine with GPU
tensor9 machine setup \
  -type Iso \
  -ip 10.0.1.20 \
  -zone datacenter-1 \
  -gpu NvidiaA100

Common Options

These options are available on most commands:

-apiKey: Your Tensor9 API key (can also use T9_API_KEY environment variable)
-vendorId: Your vendor ID (usually auto-discovered from API key)
-awsProfile: AWS CLI profile for credentials
-help: Show help for the command

Exit Codes

0: Success
1: General error
2: Command parsing error

Environment Variables

T9_API_KEY: Your Tensor9 API key

Getting Help

For command-specific help:

tensor9 <command> -help

For group-level help:

tensor9 help <group>

For general help:

tensor9 help

Install tensor9 CLI: Installation instructions
Common Workflows: Step-by-step guides for common tasks
Quick Start Guides: Get started with Tensor9

Tensor9

Getting Started

Fundamentals

Your Origin Stack

Your Customer's Environment

Integrations

tensor9 CLI

Documentation Index

​Usage

​Authentication

​Command Groups

​General Commands

​help

​env

​report

​portal

​whoami

​Vendor Commands

​vendor setup

​vendor report

​vendor upgrade

​App Commands

​app create

​app signup-link

​app list

​app retrieve

​Stack Commands

​stack publish

​stack bind

​stack unbind

​stack release create

​stack release retire

​stack list

​stack retrieve

​stack release list

​stack release download

​stack release-pending list

​stack release-bundle download

​stack release-bundle apply

​Terraform Commands

​tf import

​Form Factor Commands

​svc-spec-doc template generate

​form-factor create

​form-factor export

​form-factor promote

​form-factor retire

​form-factor evolve

​form-factor version lifecycle

​service specification document format

​Appliance Setup Commands

​appliance setup create

​appliance setup list

​appliance setup retrieve

​Appliance Commands

​appliance list

​appliance retrieve

​appliance check

​Install Commands

​install list

​Kubernetes Commands

​kube role list

​kube role enable

​kube role disable

​aws eks grant-access

​Advanced Commands

​appliance setup

​machine setup

​Common Options

​Exit Codes

​Environment Variables

​Getting Help

​Related Topics

Usage

Authentication

Command Groups

General Commands

help

env

report

portal

whoami

Vendor Commands

vendor setup

vendor report

vendor upgrade

App Commands

app create

app signup-link

app list

app retrieve

Stack Commands

stack publish

stack bind

stack unbind

stack release create

stack release retire

stack list

stack retrieve

stack release list

stack release download

stack release-pending list

stack release-bundle download

stack release-bundle apply

Terraform Commands

tf import

Form Factor Commands

svc-spec-doc template generate

form-factor create

form-factor export

form-factor promote

form-factor retire

form-factor evolve

form-factor version lifecycle

service specification document format

Appliance Setup Commands

appliance setup create

appliance setup list

appliance setup retrieve

Appliance Commands

appliance list

appliance retrieve

appliance check

Install Commands

install list

Kubernetes Commands

kube role list

kube role enable

kube role disable

aws eks grant-access

Advanced Commands

appliance setup

machine setup

Common Options

Exit Codes

Environment Variables

Getting Help

Related Topics