Skip to content
Search ⌘K
Get started

Get started with the command line

Manage the resources in your Tiger Cloud project using the Tiger CLI or REST API

Tiger Data supplies a clean, programmatic control layer for Tiger Cloud. This includes REST APIs and CLI commands that enable humans, machines, and AI agents to easily provision, configure, and manage Tiger Cloud services programmatically.

Tiger CLI is a command-line interface that you use to manage Tiger Cloud resources including VPCs, services, read replicas, and related infrastructure. Tiger CLI calls Tiger REST API to communicate with Tiger Cloud.

This page shows you how to install and set up secure authentication for Tiger CLI, then create your first service.

Prerequisites

To follow the steps on this page:

Install and configure Tiger CLI

  1. Install Tiger CLI

    Use the terminal to install the CLI:

    Terminal window
    curl -s https://packagecloud.io/install/repositories/timescale/tiger-cli/script.deb.sh | sudo os=any dist=any bash
    sudo apt-get install tiger-cli
  2. Set up API credentials

    1. Log Tiger CLI into your Tiger Cloud account:

      Terminal window
      tiger auth login

      Tiger CLI opens Console in your browser. Log in, then click Authorize. You can have a maximum of 10 active client credentials. If you get an error, open credentials and delete an unused credential.

    2. Select a Tiger Cloud project:

      Auth URL is: https://console.cloud.tigerdata.com/oauth/authorize?client_id=lotsOfURLstuff
      Opening browser for authentication...
      Select a project:
      

      > 1. Tiger Project (tgrproject)
      2. YourCompany (Company wide project) (cpnproject)
      3. YourCompany Department (dptproject)
      

      Use ↑/↓ arrows or number keys to navigate, enter to select, q to quit

      If only one project is associated with your account, this step is not shown. Where possible, Tiger CLI stores your authentication information in the system keychain/credential manager. If that fails, the credentials are stored in ~/.config/tiger/credentials with restricted file permissions (600). By default, Tiger CLI stores your configuration in ~/.config/tiger/config.yaml.

  3. Test your authenticated connection to Tiger Cloud by listing services
    Terminal window
    tiger service list

    This call returns something like:

    • No services:

      🏜️  No services found! Your project is looking a bit empty.
      🚀 Ready to get started? Create your first service with: tiger service create

    • One or more services:

      ┌────────────┬─────────────────────┬────────┬─────────────┬──────────────┬──────────────────┐
      │ SERVICE ID │        NAME         │ STATUS │    TYPE     │    REGION    │     CREATED      │
      ├────────────┼─────────────────────┼────────┼─────────────┼──────────────┼──────────────────┤
      │ tgrservice │ tiger-agent-service │ READY  │ TIMESCALEDB │ eu-central-1 │ 2025-09-25 16:09 │
      └────────────┴─────────────────────┴────────┴─────────────┴──────────────┴──────────────────┘

Create your first Tiger Cloud service

Create a new Tiger Cloud service using Tiger CLI:

  1. Submit a service creation request

    By default, Tiger CLI creates a service with 0.5 CPU and 2 GB memory with the time-series capability

    Terminal window
    tiger service create

    To control the service configuration, use the service create flags. For example, to create a free service, call tiger service create --memory shared --cpu shared.

    Note

    Free services are currently in beta.

    Free services with shared CPU/memory are only available in the us-east-1 region. Standard services can be created in any available AWS or Azure region using the --region flag.

    Tiger Cloud creates a Development environment for you. That is, no delete protection, high-availability, spooling or read replication. You see something like:

     🚀 Creating service 'db-11111' (auto-generated name)...
     ✅ Service creation request accepted!
     📋 Service ID: tgrservice
     🔐 Password saved to system keyring for automatic authentication
     🎯 Set service 'tgrservice' as default service.
     ⏳ Waiting for service to be ready (wait timeout: 30m0s)...
     🎉 Service is ready and running!
    🔌 Run 'tiger db connect' to connect to your new service
    ┌───────────────────┬──────────────────────────────────────────────────────────────────────────────────────────────────┐
    │     PROPERTY      │                                              VALUE                                               │
    ├───────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────┤
    │ Service ID        │ tgrservice                                                                                       │
    │ Name              │ db-11111                                                                                         │
    │ Status            │ READY                                                                                            │
    │ Type              │ TIMESCALEDB                                                                                      │
    │ Region            │ us-east-1                                                                                        │
    │ CPU               │ 0.5 cores (500m)                                                                                 │
    │ Memory            │ 2 GB                                                                                             │
    │ Direct Endpoint   │ tgrservice.tgrproject.tsdb.cloud.timescale.com:39004                                             │
    │ Created           │ 2025-10-20 20:33:46 UTC                                                                          │
    │ Connection String │ postgresql://tsdbadmin@tgrservice.tgrproject.tsdb.cloud.timescale.com:0007/tsdb?sslmode=require │
    │ Console URL       │ https://console.cloud.tigerdata.com/dashboard/services/tgrservice                                │
    └───────────────────┴──────────────────────────────────────────────────────────────────────────────────────────────────┘

    This service is set as default by the CLI.

  2. Check the CLI configuration
    Terminal window
    tiger config show

    You see something like:

    api_url:     https://console.cloud.tigerdata.com/public/api/v1
    console_url: https://console.cloud.tigerdata.com
    gateway_url: https://console.cloud.tigerdata.com/api
    docs_mcp:       true
    docs_mcp_url:   https://mcp.tigerdata.com/docs
    project_id:  tgrproject
    service_id:  tgrservice
    output:      table
    analytics:   true
    password_storage: keyring
    debug:       false
    config_dir:  /Users/<username>/.config/tiger

And that is it, you are ready to use Tiger CLI to manage your services in Tiger Cloud.

Commands

You can use the following commands with Tiger CLI. For more information on each command, use the -h flag. For example: tiger auth login -h

CommandSubcommandDescription
authManage authentication and credentials for your Tiger Cloud account
loginCreate an authenticated connection to your Tiger Cloud account. For non-interactive login, use flags:
  • --public-key: public key for authentication
  • --secret-key: secret key for authentication
You can also use environment variables TIGER_PUBLIC_KEY, TIGER_SECRET_KEY, and TIGER_PROJECT_ID
logoutRemove the credentials used to create authenticated connections to Tiger Cloud
statusShow your current authentication status and project ID. Possible flags are:
  • --output, -o: set output format to json, yaml, or table
versionShow information about the currently installed version of Tiger CLI. Possible flags are:
  • --check: force check for updates (regardless of last check time)
  • --output, -o: set output format to table, json, yaml, or bare
configManage your Tiger CLI configuration
showShow the current configuration. Possible flags are:
  • --output, -o: set output format to json, yaml, or table
  • --no-defaults: do not show default values for unset fields
  • --with-env: apply environment variable overrides
set <key> <value>Set a specific value in your configuration. For example, tiger config set debug true
unset <key>Clear the value of a configuration parameter. For example, tiger config unset debug
resetReset the configuration to the defaults. This also logs you out from the current Tiger Cloud project
serviceManage the Tiger Cloud services in this project
createCreate a new service in this project. Possible flags are:
  • --name: service name (auto-generated if not provided)
  • --addons: addons to enable. Possible values are time-series, ai. Set to none for vanilla PostgreSQL
  • --region: region code where the service will be deployed. Free services (shared CPU/memory) must use us-east-1
  • --cpu: CPU allocation in millicores. Set to shared to create a free service. See the allowed CPU/memory configurations below.
  • --memory: memory allocation in gigabytes. Set to shared to create a free service. See the allowed CPU/memory configurations below.
  • --replicas: number of high-availability replicas
  • --environment: environment tag. Possible values: DEV, PROD (default: DEV)
  • --no-wait: don’t wait for the operation to complete
  • --wait-timeout: wait timeout duration (for example, 30m, 1h30m, 90s)
  • --no-set-default: don’t set this service as the default service
  • --with-password: include password in output
  • --output, -o: set the output format to json, yaml, env, or table

Allowed CPU/memory configurations are:
  • shared / shared (only available in us-east-1)
  • 0.5 CPU (500m) / 2GB
  • 1 CPU (1000m) / 4GB
  • 2 CPU (2000m) / 8GB
  • 4 CPU (4000m) / 16GB
  • 8 CPU (8000m) / 32GB
  • 16 CPU (16000m) / 64GB
  • 32 CPU (32000m) / 128GB
Note: You can specify both CPU and memory together, or specify only one (the other will be automatically configured).
delete <service-id>Delete a service from this project. This operation is irreversible and requires confirmation by typing the service ID
fork <service-id>Fork an existing service to create a new independent copy. Key features are:
  • Timing options (exactly one required):
    • --now: fork at current database state
    • --last-snapshot: fork at last existing snapshot (faster)
    • --to-timestamp: fork at specific point in time (RFC3339 format)
  • Resource configuration:
    • --cpu: CPU allocation in millicores. Set to shared to create a free service. If not specified, inherits from source service. See the allowed CPU/memory configurations in the create subcommand
    • --memory: memory allocation in gigabytes. Set to shared to create a free service. If not specified, inherits from source service. See the allowed CPU/memory configurations in the create subcommand
  • Naming and environment:
    • --name <name>: defaults to {source-service-name}-fork
    • --environment: environment tag. Possible values: DEV, PROD (default: DEV)
  • Wait behavior:
    • --no-wait: don’t wait for operation to complete
    • --wait-timeout: wait timeout duration (default: 30m)
  • Default service and output:
    • --no-set-default: don’t set forked service as default
    • --with-password: include password in output
    • --output, -o: set output format to json, yaml, env, or table
get <service-id>
aliases: describe, show		Show detailed information about a specific service in this project. Possible flags are:
  • --with-password: include password in output
  • --output, -o: set output format to json, yaml, env, or table
listList all the services in this project. Possible flags are:
  • --output, -o: set output format to json, yaml, or table
update-password <service-id>Update the master password for a service. Possible flags are:
  • --new-password: new password for the tsdbadmin user
  • --auto-generate: auto-generate a secure password (mutually exclusive with --new-password)
start <service-id>Start a service that is currently inactive. Possible flags are:
  • --no-wait: don’t wait for the operation to complete
  • --wait-timeout: set the maximum wait time for this operation to complete. For example, 10m (default), 30m, 1h30m, 90s
stop <service-id>Stop a service that is currently active. After you run this command <service-id> no longer accepts connections. Possible flags are:
  • --no-wait: don’t wait for the operation to complete
  • --wait-timeout: set the maximum wait time for this operation to complete. For example, 10m (default), 30m, 1h30m, 90s
resize <service-id>Resize a service by changing CPU and memory allocation. The service may be temporarily unavailable during the resize operation. Possible flags are:
  • --cpu: CPU allocation in millicores. See the allowed CPU/memory configurations in the create subcommand
  • --memory: memory allocation in gigabytes. See the allowed CPU/memory configurations in the create subcommand
  • --no-wait: don’t wait for the operation to complete
  • --wait-timeout: set the maximum wait time for this operation to complete. For example, 10m (default), 30m, 1h30m, 90s
Note: You can specify both --cpu and --memory together, or specify only one (the other will be automatically configured).
logs <service-id>
alias: log		View logs for a service. Possible flags are:
  • --tail: number of log lines to show (default: 100)
  • --until: fetch logs before this timestamp (RFC3339 format, for example 2024-01-15T10:00:00Z)
  • --node: specific service node to fetch logs from (use 0 for primary, higher numbers for HA replicas)
  • --output, -o: set output format to text, json, or yaml (default: text)
dbDatabase operations and management
connect <service-id>Connect to a service using psql. Possible flags are:
  • --pooled: use connection pooling (default: false)
  • --role: database role/username (default: tsdbadmin)
You can also pass additional flags to psql after --. For example: tiger db connect -- --single-transaction --quiet
connection-string <service-id>Retrieve the connection string for a service. Possible flags are:
  • --pooled: use connection pooling (default: false)
  • --role: database role/username (default: tsdbadmin)
  • --with-password: include password in connection string (default: false, less secure)
create role <service-id>Create a new database role. Possible flags are:
  • --name (required): the name for the role you are creating
  • --read-only: enable permanent read-only enforcement for --name using tsdb_admin.read_only_role
  • --from: inherit grants from one or more roles. For example, --from app_role, --from readonly_role, --from app_role,readonly_role
  • --statement-timeout: set the statement timeout for --name. For example, 30s, 5m
  • --password: set the password for --name. If not provided, the CLI checks the TIGER_NEW_PASSWORD environment variable. If you have not defined TIGER_NEW_PASSWORD the CLI auto-generates a secure random password.
  • -o, --output: set the output format to json, yaml, or table
save-password <service-id>Save the password for a service. Possible flags are:
  • --role: database role/username (default: tsdbadmin)
  • --password: password value (you can also use the TIGER_NEW_PASSWORD environment variable)
test-connection <service-id>Test the connectivity to a service. Possible flags are:
  • --timeout, -t: connection timeout (default: 3s, use 0 for no timeout)
  • --pooled: use connection pooling (default: false)
  • --role: database role/username (default: tsdbadmin)
mcpManage Tiger MCP for AI Assistant integration
install [client]Install and configure Tiger MCP for a specific client. Supported clients: claude-code, codex, cursor, gemini, vscode, windsurf. If no client is specified, you’ll be prompted to select one interactively
listList all available Tiger MCP tools, prompts, and resources. Possible flags are:
  • --output, -o: set output format to json, yaml, or table
get <name>
aliases: describe, show		Get detailed information about a specific Tiger MCP capability (tool, prompt, or resource). Possible flags are:
  • --output, -o: set output format to json, yaml, or table
startStart Tiger MCP. This is the same as tiger mcp start stdio
start stdioStart Tiger MCP with stdio transport (default)
start httpStart Tiger MCP with HTTP transport. Includes flags: --port (default: 8080), --host (default: localhost)

Configuration parameters

By default, Tiger CLI stores your configuration in ~/.config/tiger/config.yaml. The location of the config directory can be adjusted via the --config-dir flag or the TIGER_CONFIG_DIR environment variable.

  • Configuration options

    You set the following configuration options using tiger config set <key> <value>:

    FlagDefaultDescription
    analyticstrueEnable or disable usage analytics
    colortrueEnable or disable colored output
    debugfalseEnable or disable debug logging
    docs_mcptrueEnable or disable the Tiger Data documentation MCP proxy
    outputtableSet the output format to json, yaml, or table
    password_storagekeyringSet the password storage method. Options are keyring, pgpass, or none
    service_id-Set the default service to manage
    version_check_interval24hSet how often the CLI checks for a new version. Set to 0 to disable

    You can also set these configuration options as environment variables. Environment variables:

    • Take precedence over configuration parameters values.
    • Are in upper case and use the TIGER_ prefix. For example, TIGER_ANALYTICS

  • Global Flags

    These flags are available on all commands and take precedence over both environment variables and configuration file values:

    FlagDefaultDescription
    --analyticstrueEnable or disable usage analytics
    --colortrueEnable or disable colored output
    --config-dir~/.config/tigerSet the directory that holds config.yaml
    --debugfalseEnable or disable debug logging
    --help, -h-Print help about the current command. For example, tiger service --help
    --password-storagekeyringSet the password storage method. Options are keyring, pgpass, or none
    --service-id-Set the default service to manage
    --skip-update-checkfalseSkip checking if a new version of Tiger CLI is available

  • Authentication parameters

    To authenticate without using the interactive login, either:

    • Set the following parameters with your client credentials, then login:
      Terminal window
      TIGER_PUBLIC_KEY=<public_key> TIGER_SECRET_KEY=<secret_key> TIGER_PROJECT_ID=<project_id>\
      tiger auth login
    • Add your client credentials to the login command:
      Terminal window
      tiger auth login --public-key=<public_key> --secret-key=<secret-key> --project-id=<project_id>