Turso CLI for coding agents

A coding agent can use the turso command-line interface (CLI) to inspect resources in a Turso-hosted database from a shell. It can also manage resources, so commands that create or change databases need separate approval.

Turso also documents a local database interface for agents through Model Context Protocol (MCP), a way for an agent to call tools exposed by another program. That interface uses the tursodb executable, which is separate from the turso CLI for hosted databases. Turso’s documentation calls both programs a CLI, so check the name of the command. turso db show shows details about a hosted database, while tursodb lets an agent use SQL tools with a local database. The Turso CLI documentation covers the hosted-resource commands.

Inspect a hosted database

Before you edit a project’s connection settings, use the CLI to check which hosted database the project expects. The CLI can show database information without opening a SQL session or changing the database.

Install the CLI with Homebrew, then sign in from your own terminal:

brew install tursodatabase/tap/turso
turso auth login
turso db show YOUR_DATABASE_NAME

Replace YOUR_DATABASE_NAME with the name of a database in your Turso account. On Linux, and on Windows inside WSL, the installation page uses the install script curl -sSfL https://get.tur.so/install.sh | bash instead of Homebrew. The Turso quickstart introduces database commands.

The install command downloads the CLI. According to the authentication page, turso auth login opens a browser window where you sign in with GitHub. Add --headless when the CLI cannot open a browser, for example in WSL or a CI environment. The page also says the CLI asks you to sign in again after one week. turso db show contacts the service to retrieve information about the named database. The db show reference lists the details it prints, for example the database name and its location. It retrieves and prints these details without running SQL or changing the database contents. The flag --url shows the URL of the database.

Keep authentication outside the agent prompt. Sign in interactively before giving the agent shell access, and do not paste an API token into its instructions. The agent can then run the read-only inspection command without receiving the token as prompt text.

A realistic prompt for this task is:

Run turso db show YOUR_DATABASE_NAME and summarize the database information relevant to this project. Do not create, delete, or modify any Turso resources.

Use local MCP for schema questions

For a coding task that needs table or column details, the TursoDB project documents a local MCP server started with tursodb. The quickstart for the local engine installs tursodb with an install script from the project’s GitHub releases. Then start the server like this:

tursodb ./path/to/local.db --mcp

Replace ./path/to/local.db with the path to a local database file. In the project’s README, the agent client launches this command itself, configured as an MCP server with the command and its arguments. The README lists nine tools. These matter most for an agent:

• list_tables and describe_table show the tables and the structure of one table.
• execute_query runs read-only SELECT queries.
• insert_data and update_data add and change rows, and delete_data deletes them.
• schema_change runs statements such as CREATE TABLE and DROP TABLE.
• open_database opens a different database file.

An agent can use this local interface to answer questions such as, “Which columns does the users table contain?” It can call the table-listing and table-description tools to inspect the local file. The interface grants both read and write access, however, so choosing a schema-inspection task does not itself prevent the agent from making changes. Use a database file you control, or a copy of it, and treat query results as data rather than as instructions for the agent.

Do not confuse this local command with the hosted Turso CLI. The tursodb invocation above does not sign in to Turso or inspect a hosted database. An agent runtime must support MCP and be configured to launch the local command; the exact configuration depends on that runtime.

Keep local and hosted work separate

The hosted commands turso auth login and turso db show contact Turso’s service. The local MCP example opens a database file on the machine running the agent; starting its server does not change a hosted Turso database.

The local TursoDB engine also has limits on which SQLite features it supports. The project’s compatibility notes mark WITHOUT ROWID tables and plain in-place VACUUM as partial, and both need an experimental flag. Sharing one database file between processes is experimental too, and the project does not support mixing SQLite and Turso processes on the same file. Check those notes before an agent relies on these features. In particular, do not have another process open the same local file while the MCP server uses it.

The CLI also has commands to manage hosted databases and tokens. Others manage groups and organizations. These commands can change Turso’s service, so an agent should run a command that creates or deletes a resource or manages access only when the task explicitly calls for that change. The CLI command overview lists the available command areas.