tiger-cli: Instructions file for Claude Code

Tiger CLI

Overview

Tiger CLI is a Go command-line interface for managing Tiger Cloud database services, built on Cobra and Viper. The same binary also runs Tiger MCP (tiger mcp start), a Model Context Protocol server that exposes service management and database operations as tools for AI assistants. CLI commands and MCP tools share their business logic through internal/common.

Naming

Use the official product names in all user-facing text (documentation, code comments, CLI output, error messages):

• Company: Tiger Data (two words, with space)
• Cloud platform: Tiger Cloud (never "TigerData Cloud" or "TigerData Cloud Platform")
• CLI tool: Tiger CLI
• MCP server: Tiger MCP
• API: Tiger Cloud API (never "TigerData API")

Repository Structure

• cmd/ - Binary entry points.
  • cmd/tiger/ - The main CLI binary. Sets up signal handling (SIGINT/SIGTERM cancel the command context), delegates to cmd.Execute(), and maps a common.ExitCodeError found anywhere in the returned error chain to the process exit code.
  • cmd/generate-docs/ - Renders the CLI reference in docs/cli/ from the command tree. Runs under go generate (see CLI Reference Docs).
• internal/ - All core application logic (non-public Go packages).
  • internal/cmd/ - Cobra command implementations for all CLI commands (auth, project, service, db, config, mcp, skills, feedback, version, upgrade, completion). Each command lives in its own file, named to match the command in snake_case (see Command Architecture). root.go holds the root command, global flags, and command tree construction; files ending in _helper.go contain cross-group helpers rather than commands.
  • internal/api/ - API client layer. Includes the OpenAPI-generated REST client (client.go, types.go), the shared HTTP client (client_util.go), and a generated mock of the client interface for testing (mocks/). Never edit the generated files by hand — see Code Generation.
  • internal/config/ - Configuration management. Handles config file loading (via Viper), the Config struct and its write helpers, and credential storage (keyring with a file fallback in the config directory).
  • internal/common/ - Shared business logic used by both CLI commands and MCP tools: the per-invocation App (config + API client), database password generation and storage (keyring, pgpass), wait/polling operations and the spinner, connection detail helpers (including read replicas), service readiness checks, query execution, log fetching, and error handling with exit codes.
  • internal/mcp/ - The Model Context Protocol (MCP) server. Each MCP tool lives in its own file, named to match the tool (see MCP Server). server.go holds server initialization, tool registration, and lifecycle management; proxy.go forwards tools from a remote documentation MCP server; capabilities.go backs mcp list/mcp get.
  • internal/analytics/ - Usage analytics tracking with sensitive-data redaction.
  • internal/util/ - Small general-purpose utilities with minimal dependencies: formatting, validation, context-aware stdin reading, JSON/YAML serialization, terminal detection.
  • internal/version/ - Version checking and update notifications.
• pkg/ - Public Go packages. Contains mcpinstall, an API for installing MCP server configurations into AI coding assistants and editors, exposed as thin aliases over the mcp install logic in internal/cmd. Changes to install behavior are part of this package's public surface.
• docs/ - Documentation. development.md is the development guide (building from source, testing, contributing).
  • docs/cli/ - The generated CLI reference, one Markdown file per command. Never edited by hand (see CLI Reference Docs).
• scripts/ - Build and installation scripts (install.sh, install.ps1, completions generation) and the integration test runner (test-integration.sh).
• openapi.yaml - OpenAPI spec for the Tiger Cloud API, from which the API client is generated. It is a verbatim copy synced from the API's own spec and is never edited here (see Code Generation).
• .github/ - GitHub Actions CI/CD workflows for testing (test.yml) and releases (release.yml).
• .goreleaser.yaml - GoReleaser configuration for building and publishing releases.
• Dockerfile - The container image published to ghcr.io/timescale/tiger-cli, which defaults to running tiger mcp start.
• docker-compose.yaml - Builds and runs that image locally.
• server-template.json - MCP registry manifest template. The release workflow substitutes the version into it to produce server.json and publishes that to the MCP registry.