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
test: Test appliance management
appliance: Customer appliance management
form-factor: Form factor management
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

update

Update the tensor9 CLI to the latest version.

tensor9 update

Options:

-customVersion (optional): A custom version to update to

Examples:

# Update to latest version
tensor9 update

# Update to specific version
tensor9 update -customVersion 1.2.3

install

Install the tensor9 CLI to make it accessible from anywhere on your system.

tensor9 install

This installs the CLI to /usr/local/bin/ so you can run tensor9 from any directory.

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

Examples:

# Basic report
tensor9 report

# Detailed report
tensor9 report -detailed

The report displays:

Vendor details
All apps and their stacks
Customer appliances
Test appliances
Active releases

console

Start a local web console for the vendor portal.

tensor9 console

Options:

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

Examples:

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

# Use custom port
tensor9 console -port 9090

# Start without opening browser
tensor9 console -noBrowser

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:

-cloud (optional): Cloud provider (aws, gcp, azure) - prompts if not provided
-region (optional): Cloud region - prompts if not provided
-awsProfile (optional): AWS profile for credentials - prompts if not provided
-apiKey (optional): Your Tensor9 API key (uses T9_API_KEY env var if not specified)
-force (optional): Force setup even if resources already exist

Examples:

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

# Non-interactive AWS setup
tensor9 vendor setup \
  -cloud aws \
  -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.

App Commands

app create

Create a new app.

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

Required:

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

Optional:

-stackType: Stack type to bind (CloudFormation, Terraform, TerraformWorkspace, DockerContainer, DockerCompose)
-nativeStackId: Native ID of the stack to bind
-vanityDomain: Custom vanity domain (e.g., anyprem.vendor.co)

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.

Stack Commands

stack publish

Publish an origin stack to your control plane.

tensor9 stack publish \
  -stackType <type> \
  -stackS3Key <key> \
  -file <path> [options]

Required:

-stackType: Stack type (TerraformWorkspace, DockerCompose, etc.)
-stackS3Key: Name for the stack archive
-file: Path to stack file (for DockerCompose) or -dir (for Terraform)

Optional:

-dir: Directory containing Terraform files (alternative to -file)

Examples:

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

# Publish Docker Compose stack
tensor9 stack publish \
  -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 to your app.

tensor9 stack bind \
  -appName <app-name> \
  -stackType <type> \
  -nativeStackId <id>

Required:

-appName: The app name
-stackType: Stack type (TerraformWorkspace, DockerCompose, CloudFormation, DockerContainer)
-nativeStackId: The native stack ID

Optional:

-stackName: A friendly name for the stack
-appVersion: App version to bind to (defaults to latest)

Examples:

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

# Bind Docker Compose stack
tensor9 stack bind \
  -appName my-app \
  -stackType DockerCompose \
  -nativeStackId "s3://t9-ctrl-000001/my-app-compose.yml"

# 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 from your app.

tensor9 stack unbind -appName <app-name>

Required (one of):

-appName: The app name
-appId: The app ID
-stackId: The Tensor9 stack ID

Examples:

# Unbind by app name
tensor9 stack unbind -appName my-app

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

stack release create

Create a release to deploy your stack to appliances.

tensor9 stack release create \
  -appName <app-name> \
  -vendorVersion <version> \
  -description <desc> \
  [target options]

Required:

-appName: The app name
-vendorVersion: Version string (e.g., “1.0.0”)
-description: Short description of the release
-notes: Detailed release notes

Target (exactly one required):

-testApplianceName: Release to a test appliance
-customerName: Release to all of a customer’s appliances
-projectionIds: JSON array of specific install IDs
-all: Release to all appliances

Optional:

-stackId or -stackName: Required if app has multiple stacks
-tuningDoc: Path to stack tuning document
-tuningDocFmt: Tuning document format (Json or Yaml, default: Json)

Examples:

# Release to test appliance
tensor9 stack release create \
  -appName my-app \
  -testApplianceName my-test-appliance \
  -vendorVersion "1.0.0" \
  -description "Initial release" \
  -notes "First production-ready version"

# Release to customer
tensor9 stack release create \
  -appName my-app \
  -customerName acme-corp \
  -vendorVersion "1.0.1" \
  -description "Bug fixes" \
  -notes "Fixed authentication issues"

# Release with tuning document
tensor9 stack release create \
  -appName my-app \
  -testApplianceName my-test-appliance \
  -vendorVersion "1.1.0" \
  -description "Performance improvements" \
  -notes "Increased resource limits" \
  -tuningDoc tuning.json

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

cd <appliance-name>
tofu init
tofu apply

stack release retire

Retire a release.

tensor9 stack release retire [options]

Required (one of):

-releaseId: The release ID to retire
OR both:
- -vendorVersion: The vendor version
- -appName: The app name

Optional:

-customerName: Filter to specific customer
-reason: 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 "1.0.0" \
  -reason "Security vulnerability fixed in 1.0.1"

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 FormFactor:
  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 SaaS, 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.

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

Required:

-appName: The app name
-formFactorName: Form factor name (must match standard naming pattern)
-env: Customer environment (Aws, Gcp, Azure, DigitalOcean, Kube, Metal, BareMetal)
-connectivity: Connectivity mode (Connected, Disconnected)

Optional:

-description: Description of the form factor (defaults to <env>+<connectivity>)
-svcSpecDoc: Path to JSON file containing service specifications (see Service specification document format)

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 a JSON service specification document for review or modification.

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

Required:

-appName: The app name
-formFactorName: The form factor name to export

Optional:

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

Examples:

# Export current 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

form-factor evolve

Evolve an existing form factor to a new version using a modified service specification document.

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

Required:

-appName: The app name
-formFactorName: The form factor name to evolve
-svcSpecDoc: Path to the modified service specification JSON file

Optional:

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

Examples:

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

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

The env and connectivity fields cannot be changed during evolution. To change these, create a new form factor instead.

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.

Test Appliance Commands

test appliance create

Create a test appliance for testing releases.

tensor9 test appliance create \
  -appName <app-name> \
  -name <appliance-name> [options]

Required (one of):

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

Optional:

-name: Test appliance name (defaults to app name + form factor)
-displayName: Friendly display name
-formFactorName: Form factor to use (defaults to same cloud as control plane, connected)
-cloudRegion: Cloud region (e.g., aws:us-west-2)

Examples:

# Create test appliance with defaults
tensor9 test appliance create \
  -appName my-app \
  -name my-test-appliance

# Create test appliance with specific form factor
tensor9 test appliance create \
  -appName my-app \
  -name my-gcp-test \
  -formFactorName gcp-connected \
  -cloudRegion gcp:us-central1

Use tensor9 report to monitor creation progress. The test appliance will be ready when its status shows “Live”.

test appliance retire

Retire a test appliance, deleting all its infrastructure.

tensor9 test appliance retire -testApplianceName <name>

Required:

-testApplianceName: The test appliance name

Examples:

tensor9 test appliance retire -testApplianceName my-test-appliance

This permanently deletes the test appliance and all its provisioned infrastructure. It may take several minutes to fully deprovision.

Appliance Commands

appliance list

List all appliances.

tensor9 appliance list

Optional:

-json: Output in JSON format

Displays detailed information about all customer and test appliances.

appliance setup create

Create a setup script for a customer to set up an appliance in their environment.

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

Required:

-customerName: The customer name
-appName: The app name
-cloud: Target cloud (Aws, Gcp, Azure, Private, Local)
-formFactorName: Form factor name

Optional:

-privateCloudName: Private cloud name (for Private cloud type)
-vendorMetadata: JSON-encoded metadata key/value pairs

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.

Advanced Commands

appliance setup

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

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

Required:

-setupKey: Single-use setup key from vendor
-cloudRegion: Cloud region (e.g., aws:us-west-2, gcp:us-central1)

Optional:

-autoApprove: Automatically approve infrastructure changes (required for non-interactive)
-domainSuffix: Domain suffix for the appliance (e.g., app.company.com)
-privateZone: Use private DNS zone instead of public
-gcpProjectId: GCP project ID (GCP only)
-resourceTags: JSON-encoded tags for cloud resources
-credentialType: Credential type for setup
-credential: Credential value

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 \
  -apiKey <key> \
  -type <type> \
  -ip <ip-address> [options]

Required:

-apiKey: Tensor9 API key
-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 \
  -apiKey <your-key> \
  -type Ctrl \
  -ip 10.0.1.10 \
  -zone datacenter-1

# Set up isolated machine with GPU
tensor9 machine setup \
  -apiKey <your-key> \
  -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

​Usage

​Authentication

​Command Groups

​General Commands

​help

​update

​install

​env

​report

​console

​Vendor Commands

​vendor setup

​App Commands

​app create

​app signup-link

​Stack Commands

​stack publish

​stack bind

​stack unbind

​stack release create

​stack release retire

​Form Factor Commands

​svc-spec-doc template generate

​form-factor create

​form-factor export

​form-factor evolve

​form-factor version lifecycle

​service specification document format

​Test Appliance Commands

​test appliance create

​test appliance retire

​Appliance Commands

​appliance list

​appliance setup create

​Advanced Commands

​appliance setup

​machine setup

​Common Options

​Exit Codes

​Environment Variables

​Getting Help

​Related Topics

Usage

Authentication

Command Groups

General Commands

help

update

install

env

report

console

Vendor Commands

vendor setup

App Commands

app create

app signup-link

Stack Commands

stack publish

stack bind

stack unbind

stack release create

stack release retire

Form Factor Commands

svc-spec-doc template generate

form-factor create

form-factor export

form-factor evolve

form-factor version lifecycle

service specification document format

Test Appliance Commands

test appliance create

test appliance retire

Appliance Commands

appliance list

appliance setup create

Advanced Commands

appliance setup

machine setup

Common Options

Exit Codes

Environment Variables

Getting Help

Related Topics