ThoughtSpot Python CLI (trcli)

Warnings

• breaking Minimum Python version requirement increased to 3.9.
  Fix: Ensure your Python environment is running Python 3.9 or newer before installing or upgrading `trcli`. Previous versions of `trcli` (e.g., < 1.13.0) supported older Python versions.
• breaking Authentication logic updated, potentially requiring re-login or new token generation.
  Fix: Users migrating from older versions (pre-1.10.0) may need to re-authenticate or update their stored authentication tokens/methods. Consult `trcli login --help` or the official documentation for the latest authentication mechanisms.
• gotcha Credentials and ThoughtSpot URL are often required and can be passed via environment variables, CLI arguments, or configuration files.
  Fix: For secure and consistent automation, it is recommended to set `TS_URL`, `TS_USERNAME`, `TS_PASSWORD`, or `TS_TOKEN` as environment variables. Alternatively, use CLI arguments (`--url`, `--username`, `--password`) or a `trcli_config.yaml` file (e.g., in `~/.thoughtspot/` or `.` directory). Ensure proper security practices for managing credentials.
• gotcha Default output format is human-readable, but programmatic interaction often requires JSON output.
  Fix: Always use the `-o json` or `--output json` flag when you need structured output that can be easily parsed by Python scripts. For example: `trcli user list -o json`.

Install

• pip install trcli Install latest version

Imports

• trcli CLI functionality
  wrong:

  from trcli.cli import main # Not a public API for general use

  correct:

  import subprocess
  import os
  
  ts_url = os.environ.get('TS_URL', 'https://your_thoughtspot_instance.com')
  ts_username = os.environ.get('TS_USERNAME', 'admin')
  ts_password = os.environ.get('TS_PASSWORD', 'password')
  
  # Example: Get trcli version
  try:
      result = subprocess.run(
          ['trcli', 'version'],
          capture_output=True, text=True, check=True
      )
      print(result.stdout)
  except subprocess.CalledProcessError as e:
      print(f"Error running trcli: {e.stderr}")
  
  # Example: Login (requires environment variables or --url/--username/--password)
  try:
      # Using environment variables is common, ensure they are set
      # os.environ['TS_URL'] = ts_url
      # os.environ['TS_USERNAME'] = ts_username
      # os.environ['TS_PASSWORD'] = ts_password
      # Note: For security, avoid hardcoding credentials. Use env vars or config.
      
      result = subprocess.run(
          ['trcli', 'login', '--url', ts_url, '--username', ts_username, '--password', ts_password],
          capture_output=True, text=True, check=True
      )
      print("Login successful:", result.stdout)
  except subprocess.CalledProcessError as e:
      print(f"Login failed: {e.stderr}")

  trcli is primarily a command-line interface. Its core functionality is exposed via the 'trcli' executable, not directly via Python library imports for general programmatic use. The recommended and safest way to interact with trcli from Python is by invoking it as a subprocess using `subprocess.run`.

Quickstart

This quickstart demonstrates how to interact with the `trcli` command-line tool from a Python script using the `subprocess` module. It includes a login attempt and a sample command to list users, highlighting the importance of handling credentials securely (e.g., via environment variables) and capturing output.

import subprocess
import os

# Set ThoughtSpot URL and credentials using environment variables for security
# Or pass them directly as arguments (less secure for passwords)
# Example environment variables (replace with your actual values):
# export TS_URL='https://your-thoughtspot-instance.com'
# export TS_USERNAME='your_username'
# export TS_PASSWORD='your_password'

# You can use os.environ.get for testing or local setup
ts_url = os.environ.get('TS_URL', 'https://localhost') # Use a placeholder or actual URL
ts_username = os.environ.get('TS_USERNAME', 'user') # Use a placeholder or actual username
ts_password = os.environ.get('TS_PASSWORD', 'pass') # Use a placeholder or actual password

print(f"Attempting to use trcli with URL: {ts_url}")

try:
    # First, try to login to obtain a session token
    # For programmatic use, consider using a service principal or persistent token
    login_cmd = [
        'trcli', 'login',
        '--url', ts_url,
        '--username', ts_username,
        '--password', ts_password
    ]
    print(f"Running login command: {' '.join(login_cmd[:4])} ...") # Censor password
    login_result = subprocess.run(login_cmd, capture_output=True, text=True, check=True)
    print("Login successful:")
    print(login_result.stdout)

    # Now, run a command, e.g., list users, outputting as JSON
    list_users_cmd = ['trcli', 'user', 'list', '-o', 'json']
    print(f"Running command: {' '.join(list_users_cmd)}")
    users_result = subprocess.run(list_users_cmd, capture_output=True, text=True, check=True)
    print("Users list (JSON):")
    print(users_result.stdout)

except FileNotFoundError:
    print("Error: 'trcli' command not found. Ensure trcli is installed and in your PATH.")
except subprocess.CalledProcessError as e:
    print(f"Error executing trcli command:\nSTDOUT: {e.stdout}\nSTDERR: {e.stderr}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")