Skip to main content

Turso CLI

The Turso CLI is the tool provided for managing Turso databases. If you are getting started for the first time, we recommend following along with the getting started tutorial, which walks you through the process of installation, authentication, creating a database, replicating it, querying it, and destroying it.

Conventions​

The example commands on this page assume the following placeholders, expressed as shell variables:

  • $DB_NAME: The name of the database that was specified or assigned during creation.
  • $LOCATION_CODE: A three-letter location code that indicate the physical location of a database instance. The command turso db locations outputs a full list of supported location codes.

Installation​

The Turso CLI has two installation options.

Homebrew (macOS and Linux)​

There is a Homebrew formula that's installed with the following command:

$ brew install chiselstrike/tap/turso

The formula includes an executable with autocompletion scripts for bash, fish, and zsh.

Scripted install​

If you prefer the manage the installation directly, run the following command to execute a shell script that downloads and installs the CLI:

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

The CLI is installed in a directory called .turso in your home directory. The shell script will attempt to add that to your shell’s PATH configuration. You will need to start a new shell to see the change, or add it manually to the current shell.

Verify the installation​

Run the following command to make sure the Turso CLI is in your PATH:

$ turso --version

Upgrade the CLI​

If Homebrew was used to install the CLI, use the following commands to update it:

$ brew update
$ brew upgrade

If you used the scripted install, use the CLI itself to update:

$ turso update

Logging in to the CLI​

The Turso CLI requires a GitHub account for authentication. You must log in to be able to work with databases. All databases created while logged in with an account belong to that account and are controlled by it. There is currently no way to share database access with other accounts.

Use the command turso auth login to start the login process. The command launches your default browser and prompts you to log in with GitHub. The first time, you are asked to grant the GitHub Turso app some permissions to your account. Accept this in order to continue. (If desired, you can revoke those permissions later in the GitHub settings for your account.)

When the authentication process finishes, you are issued an authentication token. This token identifies your account to Turso. The token expires after one week; afterward, you must log in again to get a new token.

info

The user auth tokens generated by the login command are different in purpose than the auth tokens for client access received from the turso db tokens create. They are not interchangeable.

Running locally​

If you are running the CLI on your local machine, the CLI receives this token as part of the login flow and stores it locally for future use. You can retrieve the persisted token string using:

$ turso auth token

Running remotely​

If you are running the CLI on a remote machine, it might not be able to launch a browser. In that case, use the URL provided by turso auth login with a browser you have access to in order to authenticate. The process ends with a page showing your token. You can put this string in the environment variable TURSO_API_TOKEN in a shell before running commands using a CLI that is not logged in. For example:

$ export TURSO_API_TOKEN=[YOUR-TOKEN-STRING]
$ turso db locations

Manage database instances​

Create a database​

To create a new logical database with an initial primary instance using a randomly generated name:

$ turso db create

To specify the name of the database:

$ turso db create $DB_NAME

Specify a primary location​

Turso chooses a location for the primary instance that is thought to be close to the machine running the command (using its IP address). To specify the location, use the --location flag with a location code:

$ turso db create $DB_NAME --location $LOCATION_CODE

Create a database with a SQLite database file​

To create a new logical database and seed it with the contents of an existing SQLite3-compatible database file, use the --from-file flag:

$ turso db create $DB_NAME --from-file $DB_FILE

Create a replica​

To create a replica of a logical database in a specified location:

$ turso db replicate $DB_NAME $LOCATION_CODE
info

The data from the primary instance is copied to the replica immediately after it's created. For applications using a logical database URL, Turso routes the closest client traffic to the replica immediately after replication is complete.

Destroy a replica​

To destroy a replica, first find its randomly generated name using the output of turso db show $DB_NAME. Then, use the name on the command line:

$ turso db destroy --instance $INSTANCE_NAME

You can also destroy a replica using its location code:

$ turso db destroy --location $LOCATION_CODE
info

Destruction of a replica is considered "safe" in that no data is lost in the process - the primary instance still contains a copy of everything.

Destroy an entire logical database​

To destroy a logical database (a primary instance and all replicas):

$ turso db destroy $DB_NAME
danger

Destruction of a logical database cannot be reversed. All copies of data are deleted. The command will prompt you to ensure this is really what you want.

Update a logical database​

To upgrade the version of sqld used for every instance in a logical database:

$ turso db update $DB_NAME

This command causes a brief moment of downtime for each instance as the upgrade happens. All existing connections are closed and must be reconnected. The libSQL client libraries do this automatically.

You can check the version of sqld for each instance using turso db show $DB_NAME.

Authentication tokens for client access​

Client access to Turso from your application requires a database authentication token. This token should be long-lived, and different from the token you get when you log in to the CLI. To get an auth token suitable for your app, run the following command:

$ turso db tokens create $DB_NAME

$DB_NAME is the name of your database. This command outputs an auth token string that you can use the configure the libSQL client library, along with the database URL. This token never expires.

info

The client auth tokens generated by the turso db tokens create command are different in purpose than the user auth tokens received from logging in to the CLI. They are not interchangeable.

Auth token expiration​

If you want to put a limit on how much time an auth token is valid, use the --expiration flag to specify a duration in days. For example, for a 7-day token:

$ turso db tokens create $DB_NAME --expiration 7d

Revoke auth tokens​

Treat any auth token as a secret only for use by your application backend. If this token is ever leaked, you can invalidate all prior auth tokens for your database with the following command:

$ turso db tokens invalidate $DB_NAME

This command restarts all of your database instances in order to use a new signing key for any new tokens you create afterward.

Read-only auth tokens​

To generate an auth token that has read-only access to the database.

$ turso db tokens invalidate $DB_NAME --read-only

Read-only tokens enable a client to run queries with select, but disallow update, insert, and delete commands.

Inspect database usage​

Total database usage, measured for the purpose of billing, is aggregated across all [logical databases] associated with an account. The billable metrics are:

  • Total amount of storage
  • Number of rows read

To see a summary for your account, use the following command:

$ turso account show

You can get more detailed data about the current usage of a logical database using the following command:

$ turso db inspect $DB_NAME

This reports the total space occupied by all user-created tables and indexes. For a more detailed breakdown by location, table, and index, pass the --verbose flag.

info

During the public beta, Turso is free to use with limits. In the future, you will be billed according to your usage.

Database dump and load​

You can dump the entire contents of a Turso database using the following command:

$ turso db shell $DB_NAME .dump > dumpfile.sql

The file dumpfile.sql contains all of the SQL commands necessary to rebuild the database. libSQL and SQLite internal tables are not present.

note

.dump is a command you can run in the interactive shell, but you should consider running it on the command line so its output can be easily saved in a file.

After creating a dump file, you can then load the dumped data into a new database using the following command:

$ turso db shell $NEW_DB_NAME < dumpfile.sql

Embedded sqld​

The Turso CLI comes with an embedded sqld that you can use for local development instead of a managed Turso database. To start the server on port 8080, run:

$ turso dev

This starts sqld using an in-memory database. To persist data in a SQLite database file, specify the path of the file:

$ turso dev --db-file path/to/db-file

The CLI outputs a URL you can use to connect to the embedded sqld. Use this URL instead of the Turso database libsql URL when building locally. This URL can be used with turso db shell and the libSQL client libraries.

You can change the port of the embedded sqld with the --port flag.

Get help​

The CLI offers help for all commands and subcommands. Run turso help to get a list of all commands. Use the --help flag to get help for a specific command or subcommand. For example: turso db --help.

Local storage​

The CLI stores persistent data, including your auth token, in a file on your computer. On macOS, the containing folder is $HOME/Library/Application Support/turso. On Linux, it’s $HOME/.turso. It is safe to delete this folder, since it can be restored by logging in to the CLI again.