Strata CLI

Command-line interface for the Strata Semantic Analytics System. Create, manage, and deploy Strata projects with ease.

Installation

Basic Installation

gem install strata-cli

Requirements

  • Ruby >= 3.4.4
  • Git (for deployment features)

Dependencies

Adapter Gems and System Libraries

Commands Overview

💡 Tip: Run strata COMMAND --help for detailed help, options, and examples on any command. The CLI help system provides comprehensive documentation for each command.

Agent mode (--agent)

Pass --agent on any command for structured JSON output and no interactive prompts (where the command supports it).

Supported examples:

strata datasource list --agent
strata datasource tables my_db --agent
strata datasource meta my_db orders --agent
strata table list --agent
strata audit all --agent
strata deploy --yes --agent

Not supported — these commands are interactive generators; write YAML directly instead:

strata create table [TABLE_PATH]      # → models/tbl.*.yml
strata create relation RELATION_PATH  # → models/rel.*.yml

Use strata datasource meta DS_KEY TABLE_NAME --agent for column metadata when authoring table models.

Project Management

strata init [PROJECT_NAME]

Initialize a new Strata project or clone from an existing repository.

Options:

  • -d, --datasource ADAPTER - Add datasource adapters (repeatable)
  • -s, --source URL - Clone existing project from URL
  • -a, --api-key KEY - API key (required with --source)

Examples:

strata init my-project
strata init my-project -d postgres -d snowflake
strata init --source https://github.com/org/project.git --api-key YOUR_KEY

strata project link PROJECT_ID

Link local project to an existing project on the Strata server.

Examples:

strata project link 12345
Datasource Management (alias: `ds`)

strata datasource adapters

List all supported data warehouse adapters.

strata datasource check

Check which database adapter gems are installed.

strata datasource list

List all configured datasources with their keys and display names.

strata datasource add [ADAPTER]

Add a new datasource interactively. ADAPTER is optional - prompts if omitted.

Examples:

strata datasource add              # Interactive mode
strata datasource add postgres     # Direct selection
strata ds add snowflake            # Using alias

strata datasource auth DS_KEY

Set credentials for a datasource. Credentials stored in .strata file.

strata datasource test DS_KEY

Test connection to a datasource.

Examples:

strata datasource test my_db

strata datasource tables [DS_KEY]

List all tables in a datasource with interactive filtering.

Options: -p, --pattern PATTERN, -c, --catalog CATALOG, -s, --schema SCHEMA

Examples:

strata datasource tables my_db
strata datasource tables my_db -p user -s dbo

strata datasource meta DS_KEY TABLE_NAME

Show the schema/structure of a specific table.

Options: -c, --catalog CATALOG, -s, --schema SCHEMA

Examples:

strata datasource meta my_db customers
strata datasource meta my_db dbo.orders

strata datasource exec DS_KEY

Execute SQL queries on a datasource.

Options: -q, --query QUERY, -f, --file PATH

Examples:

strata datasource exec my_db -q "SELECT * FROM customers LIMIT 10"
strata datasource exec my_db -f queries/analysis.sql
Model Creation

strata create table [TABLE_PATH]

Create a semantic table model from a datasource table. Not available with --agent — write models/tbl.*.yml directly or use strata datasource meta for schema metadata.

Options: -d, --datasource DS_KEY

Examples:

strata create table                        # Interactive mode
strata create table call_center             # Simple path
strata create table games/event_details     # Nested path
strata create table contact/dse.call_center_d  # With schema

Process: Checks table existence → Fetches metadata → AI suggests fields → Interactive editor → Generates model file

strata create relation RELATION_PATH

Create a relation (join) definition file. Not available with --agent — write models/rel.*.yml directly.

Options: -d, --datasource DS_KEY

Examples:

strata create relation customer/orders    # Creates models/customer/rel.orders.yml
strata create relation customer           # Creates models/rel.customer.yml

strata create migration rename

Create a migration file to rename an entity.

Options: -e, --entity TYPE (required), -f, --from NAME (required), -t, --to NAME (required)

Entity types: dimension, measure, table, datasource

Examples:

strata create migration rename -e dimension -f old_name -t new_name
strata create migration rename -e table -f old_table -t new_table

strata create migration swap

Create a migration file to swap entity references.

Options: -e, --entity TYPE (required), -f, --from NAME (required), -t, --to NAME (required)

Entity types: dimension, measure, table (datasource not supported)

Examples:

strata create migration swap -e measure -f measure_a -t measure_b
Table Management (aliases: `t`, `tbl`)

strata table list

List all semantic table models in the project.

Examples:

strata table list
strata t list
Deployment

strata deploy

Deploy project to Strata server for the current branch.

Options:

  • -e, --environment ENV - Deploy to specific environment
  • --skip-audit - Skip pre-deployment audit checks
  • --yes, -y - Skip confirmation prompts (CI/CD mode)
  • -f, --force - Force deploy even if no files changed

Examples:

strata deploy
strata deploy -e production
strata deploy --skip-audit --yes    # CI/CD mode
strata deploy --force

Process: Audit checks → Git status → Create archive → Upload → Monitor progress

strata deploy status

Show current deployment status for the active branch.

Options: -e, --environment ENV

Examples:

strata deploy status
strata deploy status -e production
Audit & Validation (alias: `a`)

strata audit or strata audit all

Run all audit checks (syntax, models, connections). This is the default command.

strata audit syntax

Check YAML syntax of all configuration files.

strata audit models

Validate model definitions and schema structure.

strata audit connections

Test all datasource connections.

Examples:

strata audit              # Run all checks
strata audit syntax       # Check YAML syntax only
strata a models           # Validate models only
Utilities

strata version

Print the CLI version.

strata check

Check which database adapter gems are installed (no project required).

strata adapters

List all supported data warehouse adapters.

Configuration

Project Configuration (project.yml)

Main project configuration file:

name: My Project
uid: my-project
description: Description of my project
server: https://strata.example.com
production_branch: main
git: https://github.com/org/project.git
project_id: 123  # Auto-populated after first deployment

Multi-Environment Configuration:

# Default environment
server: http://localhost:3000

# Environment-specific configs
staging:
  server: https://staging.strata.com
  api_key: staging-key

production:
  server: https://app.strata.com
  api_key: prod-key

Local Configuration (.strata)

Stores sensitive credentials. Never committed to git (automatically excluded).

api_key: your-api-key-here

# Datasource credentials
my_db:
  username: user
  password: pass

# AI configuration (optional)
ai_provider: openai
ai_api_key: your-ai-key

Security: The .strata file automatically has restrictive permissions (0600) for security.

Datasources Configuration (datasources.yml)

Defines all datasource connections:

my_postgres:
  adapter: postgres
  name: PostgreSQL Database
  host: localhost
  port: 5432
  database: mydb
  schema: public
  ssl: false
  tier: warm
  query_timeout: 3600

my_snowflake:
  adapter: snowflake
  name: Snowflake Warehouse
  account_identifier: myorg-myaccount
  database: ANALYTICS_DB
  warehouse: COMPUTE_WH
  schema: PUBLIC
  role: ACCOUNTADMIN
  auth_mode: pat

my_databricks:
  adapter: databricks
  name: Databricks Warehouse
  host: workspace.cloud.databricks.com
  warehouse: warehouse_id
  catalog: main
  schema: default
  auth_mode: oauth_m2m

my_clickhouse:
  adapter: clickhouse
  name: ClickHouse
  protocol: http
  host: localhost
  port: 8123
  database: default
  username: default
  tier: warm
  query_timeout: 3600

Databricks authentication

Databricks now requires explicit auth_mode.

If you already have Databricks datasources, update datasources.yml:

my_databricks:
  adapter: databricks
  auth_mode: oauth_m2m

Use service principal credentials and run strata ds auth my_databricks to save oauth_client_id and oauth_client_secret in .strata.

Supported Data Warehouse Adapters

  • PostgreSQL - Full support
  • MySQL - Full support
  • SQL Server - Full support (including Azure)
  • Snowflake - Full support (PAT, Key Pair)
  • Athena - AWS Athena support
  • Trino - Trino/Presto support
  • DuckDB - Embedded analytics database
  • Druid - Apache Druid support
  • Redshift - Amazon Redshift support
  • Databricks - Databricks SQL warehouse support
  • ClickHouse - ClickHouse HTTP/native SQL support
  • SQLite - SQLite database support

Security

  • ✅ Credentials stored in .strata with restrictive permissions (0600)
  • ✅ API keys never accepted via command line arguments
  • ✅ File paths validated to prevent path traversal attacks
  • ✅ Git commit hashes validated before use
  • ✅ YAML files loaded safely to prevent code execution

Troubleshooting

Common Issues

"Permission denied" errors

Ensure you have write permissions in the project directory. The .strata file permissions are automatically set to 0600.

"Server URL not configured"

Add the server field to your project.yml:

server: https://your-strata-server.com

"API key not found"

Run strata deploy and enter your API key when prompted, or manually add to .strata:

api_key: your-api-key

"Uncommitted changes" during deploy

Commit or stash your changes:

git add .
git commit -m "Your changes"
strata deploy

"Table not found" when creating model

  • Verify the table exists in the datasource
  • Check schema/catalog settings
  • Use strata datasource tables DS_KEY to list available tables
  • Use strata datasource meta DS_KEY TABLE_NAME to verify table structure

Connection test failures

  • Verify credentials with strata datasource auth DS_KEY
  • Check network connectivity
  • Verify datasource configuration in datasources.yml
  • Test connection with strata datasource test DS_KEY

Development

After checking out the repo:

bundle install

Run tests:

rake test

Release a new version:

  1. Update version in lib/strata/cli/version.rb
  2. Update CHANGELOG.md with the new version and changes
  3. Commit and merge to master: git add lib/strata/cli/version.rb CHANGELOG.md && git commit -m "Bump version to X.Y.Z" (then open a PR and merge)
  4. Via GitHub Actions (recommended): In the repo go to Actions → Release → Run workflow, choose the branch (e.g. master), optionally enable "Build and test only" for a dry run, then Run workflow. Ensure the repo secret RUBYGEMS_API_KEY is set (RubyGems API key with push permission).
  5. Via console: From a checkout of master after the version-bump merge, run bundle exec rake release (builds gem, creates git tag, pushes tag and gem to RubyGems).

Contributing

Bug reports and pull requests welcome on GitHub at https://github.com/stratasite/strata-cli.

License

The gem is available as open source under the terms of the MIT License.