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 commandturso 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.
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
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
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
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.
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.
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.
.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.