Turso CLI Installation Guide - SQLite Without The Server Hell

Look, I've installed enough database CLIs to know they usually break in creative ways. Postgres psql needs 47 environment variables set just right. MongoDB's CLI randomly forgets how to connect. MySQL's CLI still feels like it's from 1995.

Turso CLI is different. As of September 2025, it actually fucking works on the first try. They're pushing updates every few weeks - audit logging, database branching, performance improvements. Someone's clearly eating their own dog food because this thing doesn't feel abandoned like half the database tools gathering dust on GitHub.

Homebrew Installation (Usually Works, Sometimes Doesn't)

If you're on macOS or Linux, start here:

brew install tursodatabase/tap/turso

Homebrew is usually the fastest route unless brew decides to rebuild half the universe because you touched a dependency. Takes 30 seconds on a good day, 20 minutes if you're unlucky.

After installation, the binary should be in your PATH. Should be. If you get command not found: turso, restart your terminal or run source ~/.zshrc (macOS) or source ~/.bashrc (Linux). On macOS Monterey and newer, sometimes the PATH doesn't update until you close everything and open a new terminal window. Don't ask me why.

To upgrade when they inevitably fix something you didn't know was broken:

brew upgrade turso

Universal Install Script (For When Homebrew Breaks)

For all Unix-like systems, there's the usual curl-pipe-bash approach:

curl -sSfL https://get.tur.so/install.sh | bash

The script detects your platform automatically unless you're on some weird ARM setup or Alpine Linux, which confuses the hell out of everything. Drops the binary in /usr/local/bin and needs sudo access.

The install script works great until you're behind a corporate firewall. Then you'll spend 2 hours figuring out HTTP_PROXY and HTTPS_PROXY settings, only to discover your company blocks the domain entirely. If you see "Connection refused" or timeouts, blame your network team.

Go Installation (For the Masochistic)

If you're already in the Go ecosystem and have Go set up:

go install github.com/tursodatabase/turso-cli/cmd/turso@latest

Go installation looks deceptively simple until you realize:

1. You need Go 1.21+ and your Ubuntu box has 1.19 from the stone age
2. Your $GOPATH/bin isn't in PATH (it never fucking is)
3. The build fails with some cryptic dependency error about golang.org/x/sys

When it works, it works great. When it doesn't, you'll question your life choices. The binary ends up in $GOPATH/bin/turso or ~/go/bin/turso if you didn't set GOPATH.

Manual Binary Download

Download pre-compiled binaries from GitHub releases for your platform:

• Linux AMD64: turso-linux-amd64
• Linux ARM64: turso-linux-arm64
• macOS AMD64: turso-darwin-amd64
• macOS ARM64: turso-darwin-arm64
• Windows: turso-windows-amd64.exe

Extract and add to your $PATH manually. This approach works for air-gapped environments or when you need specific version control.

Verification and Initial Setup

After installation, make sure it actually works:

turso --version

If you get command not found, the binary isn't in your PATH. Check your shell config file and add the path, then restart your terminal.

Config files get scattered across your system like every other CLI tool:

• Linux: ~/.config/turso/settings.json (or wherever XDG Base Directory thinks it should be)
• macOS: ~/Library/Application Support/turso/settings.json (buried in Application Support)
• Windows: %APPDATA% urso\settings.json

The config file has your auth tokens. Don't commit this to Git unless you want to leak your API keys to everyone. For CI/CD, use environment variables instead of config files. The auth docs cover headless authentication for automated deployments.

Getting Started with Authentication (aka The OAuth Shitshow)

The CLI needs to talk to Turso Cloud, so you get to dance the authentication tango. For new users:

turso auth signup

This tries to launch your default browser for GitHub OAuth. "Tries" being the operative word here. Sometimes it opens Internet Explorer on Windows (yes, really). Sometimes it opens nothing at all. Sometimes it opens your browser but to the wrong URL.

For existing users who already went through this pain:

turso auth login

OAuth login breaks in the stupidest ways. I've seen it:

• Hang forever on WSL2 because the browser bridge is fucked
• Fail silently on Linux desktop environments that hate life
• Open the browser but not actually complete the handshake
• Work perfectly 9 times, then randomly break on attempt 10

When OAuth decides to shit the bed, kill the process (Ctrl+C) and use the headless version:

turso auth login --headless

This gives you a URL to copy-paste manually, which actually works reliably. Perfect for CI/CD environments or when your desktop decides browsers are optional today.

Database Management (That Usually Works)

Creating Databases

## Auto-generated name in closest location
turso db create

## Specify database name (do this or you'll get random garbage)
turso db create my-project-db

## Create in specific location
turso db create my-db --location ord

The CLI picks the closest location automatically. Usually works fine - gets you Chicago, Frankfurt, Sydney, whatever's closest. Sometimes it picks weird locations for no apparent reason.

turso db create will shit itself if you pick a name someone already took globally. Yes, it's globally namespaced across all Turso users, which is fucking annoying until you realize it prevents name conflicts. You'll get this useless error:

Error: database name 'test' is already taken

Cool, thanks. Try my-test-db-2025 or test-dont-delete like the rest of us.

Database Operations

## List all databases (check if you created too many)
turso db list

## Show database details and connection info
turso db show my-db

## Get connection URL for applications
turso db show my-db --url

## Delete database (there's no undo button)
turso db destroy my-db

Interactive SQL Shell

Access your database directly from the terminal:

## Launch interactive shell
turso db shell my-db

## Execute single command
turso db shell my-db \"SELECT * FROM users LIMIT 5\"

## Run SQL file
turso db shell my-db < migration.sql

The shell uses SQLite syntax with some extra libSQL features for vector search and other stuff.

Database Replication and Groups

Location Management

## List available edge locations
turso db locations

## Replicate database to multiple regions
turso db replicate my-db lhr  # London
turso db replicate my-db syd  # Sydney

Replication reduces latency by creating read replicas in multiple regions. The edge architecture puts your data closer to users with sub-100ms latency worldwide. The replication system handles conflict resolution automatically.

Group Management

Groups manage databases sharing the same schema across locations:

## Create group with primary location
turso group create production-group --location ord

## Add locations to group
turso group locations add production-group fra

## Create database in group
turso db create prod-db --group production-group

Groups enable schema synchronization and consistent replication policies across related databases. The Multi-DB Schema feature supports database-per-tenant architectures with automatic schema migrations across thousands of databases.

Token and Access Management

API Tokens

## Create read-write token for specific database
turso db tokens create my-db

## Create read-only token
turso db tokens create my-db --readonly

## Token with expiration
turso db tokens create my-db --expiration 1h

The token system supports fine-grained permissions including ATTACH permissions for multi-database queries. For production deployments, use long-lived tokens with appropriate scoping.

Organization Management

## View current organization
turso org show

## Invite team members
turso org invite user@company.com

## Manage billing (requires admin role)
turso plan show
turso plan upgrade

The CLI integrates with Turso's pricing tiers and organization features for team collaboration. Billing management includes usage monitoring and overage controls, while team management supports role-based access across enterprise deployments.