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.

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:** ```bash 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:** ```bash 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:** ```bash 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. **Options:** `-r, --remote` - Set credentials on remote server **Examples:** ```bash strata datasource auth my_db strata ds auth postgres_db --remote ``` ### `strata datasource test DS_KEY` Test connection to a datasource. **Examples:** ```bash 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:** ```bash 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:** ```bash 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:** ```bash 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. **Options:** `-d, --datasource DS_KEY` **Examples:** ```bash 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. **Options:** `-d, --datasource DS_KEY` **Examples:** ```bash 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:** ```bash 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:** ```bash 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:** ```bash 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:** ```bash 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:** ```bash 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:** ```bash 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

Supported Data Warehouse Adapters

  • PostgreSQL - Full support
  • MySQL - Full support
  • SQL Server - Full support (including Azure)
  • Snowflake - Full support (PAT, Key Pair, OAuth)
  • Athena - AWS Athena support
  • Trino - Trino/Presto support
  • DuckDB - Embedded analytics database
  • Druid - Apache Druid 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`: ```yaml 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`: ```yaml api_key: your-api-key ``` ### "Uncommitted changes" during deploy Commit or stash your changes: ```bash 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.