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:
$GROUP_NAME: The name of a placement group to work with$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 locationsoutputs 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 tursodatabase/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 attempts to add that to your shell’s PATH configuration. You must
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 a user 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 turso auth login command are different
in purpose from database auth tokens for client access
and platform API tokens. 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 placement groups and logical databases
When working with placement groups, note that they count toward the maximum database allowance in your billing plan, even if you haven’t yet created a database within the group. A placement group requires one database "unit" for each location in the group, and you must have that capacity available in your organization when you create a placement group or expand it to another location.
Create a placement group
To create a new placement group using a primary location with the lowest latency to the machine where the command is run:
$ turso group create $GROUP_NAME
You can specify the location using the --location flag, providing the
location's three letter code.
It costs one database from your billing plan’s allowance to create a placement group.
Every placement group is assigned to an organization which is used for collaboration and billing. When you create a database, the CLI uses the current organization as the container. By default, the CLI assumes a personal organization with the same name as your GitHub username.
Create a logical database within a group
To create a new logical database with a random name in the named placement group:
$ turso db create --group $GROUP_NAME
To specify the name of the database:
$ turso db create $DB_NAME --group $GROUP_NAME
If you omit the --group flag:
- If you have only one placement group, it is used.
- If you don't have any placement groups, one is created using the name "default".
Create a logical database using 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 --group $GROUP_NAME --from-file $DB_FILE
The file is limited to 2GB is size.
Create a logical database using a SQLite database dump
To create a new logical database and seed it with the contents of an existing
SQLite database dump, use the --from-dump flag:
$ turso db create $DB_NAME --group $GROUP_NAME --from-dump $SQL_FILE
The file must be a text file with SQL commands. It is typically generated by the
.dump command or the Turso CLI or SQLite CLI.
Create a logical database by copying another logical database
To create a new database with the same contents as an existing database in your organization:
$ turso db create $DB_NAME --group $GROUP_NAME --from-db $OTHER_DB_NAME
Create a logical database by copying another logical database at a point in time
To create a new database with the same contents as an existing database in your
organization, with contents specified from a specific point in time, use the
--timestamp flag with --from-db:
$ turso db create $DB_NAME --group $GROUP_NAME --from-db $OTHER_DB_NAME --timestamp $RFC3339
The --timestamp argument must be a timestamp with RFC3339 format (see
timestamp examples).
This can be used to eventually restore a database to contents from a particular point in time. After making a copy like this, you must delete the original database and recreate it with the contents of the newly created database.
The contents of the newly created database contains data strictly before the given timestamp. It also might be missing up to 15 seconds of data before the timestamp, depending on when Turso last created a periodic batch checkpoint.
Replicate a database by adding a location to a group
You can replicate a logical database by adding a location to its placement group. To add a location:
$ turso group locations add $GROUP_NAME $LOCATION_CODE
It costs one database from your billing plan’s allowance to add a location to a placement group, no matter how many logical databases are contained within that group.
Adding a replica location to a group effectively replicates all logical databases in that group, since they each share the same deployment and replication behavior on the same hardware.
Client applications using a logical database URL are routed to the new location if it's observed to have the lowest latency among all available locations in the group.
Similarly, you can remove a replica location from a placement group:
$ turso group locations remove $GROUP_NAME $LOCATION_CODE
Removing a replica location is considered "safe" in that doesn't eliminate any of the data in any logical database. The primary location always retains a copy of everything.
You can list the locations of a placement group using the list subcommand:
$ turso group locations list $GROUP_NAME
Destroy a logical database
Destruction of a logical database cannot be reversed. All copies of data are deleted. The command prompts you to ensure this is really what you want.
To destroy a logical database (from all locations, including the primary):
$ turso db destroy $DB_NAME
Destroy a placement group
Destroying a placement group permanently deletes all copies of all databases in the group.
To destroy an existing placement group:
$ turso group destroy $GROUP_NAME
Update the libSQL server version of a placement group
To upgrade the version of libSQL server used for every logical database in a placement group:
$ turso group update $GROUP_NAME
This command causes a brief moment of downtime for each instance as the update happens. All existing connections are closed and must be reconnected. The libSQL client libraries do this automatically.
To check the version of libSQL server for a logical database:
$ turso db show $DB_NAME
Database client authentication tokens
Client access to query a Turso database from your application requires a database authentication token. Treat any database token as a secret for use only by your application backend.
The database auth tokens generated by the turso db tokens create command are
different in purpose from the user auth tokens received from logging in to the
CLI and platform API auth
tokens. They are not interchangeable.
Creating a database token
To get a database 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 to configure the libSQL client library wherever it
requires an "auth token" string.
Database tokens are not individually recorded by Turso. You may create as many as you want. By default, these tokens never expire.
Token expiration
If you want to put a limit on how much time a database token is valid, use the
--expiration flag to specify a duration in days. For example, for a 7-day
token, run the following:
$ turso db tokens create $DB_NAME --expiration 7d
Read-only database tokens
To generate an auth token that has read-only access to the database.
$ turso db tokens create $DB_NAME --read-only
Read-only tokens enable a client to run queries with select, but disallow
update, insert, and delete commands.
Invalidate database tokens
If a database token is ever leaked, you can invalidate all prior tokens for your database with the following command:
$ turso db tokens invalidate $DB_NAME
This command restarts all of your database instances to use a new database token signing key for any new tokens you create afterward.
Team collaboration with organizations
Turso allows you to manage team database access and billing using a grouping mechanism called "organizations". By default, the CLI assumes a personal organization with the same name as your GitHub username.
Create an organization
You can create a new organization using the CLI with the command:
$ turso org create $ORG_NAME
When the organization is created with the CLI:
- The organization is assigned a "slug" string which uniquely identifies it, based on the provided name.
- Your account is assigned the "owner" role. Only one owner per organization is supported.
- The new organization becomes the current organization for future CLI commands. You can switch to another organization as needed.
Organization slugs are globally unique. Creation of an organization fails in case its assigned slug already exists.
List organizations
To list organizations of which you are the owner or a member:
$ turso org list
Switch organizations
To change the current organization for future CLI commands, including those that work with logical databases, provide its unique slug to the following command:
$ turso org switch $ORG_SLUG
The current organization is persisted in local storage.
Delete an organization
To delete an organization and all of its associated databases and billing information:
$ turso org destroy $ORG_SLUG
Your personal organization can't be destroyed.
The CLI doesn't allow destroying an organization that is also the current organization. You must switch organizations if necessary.
Manage members of an organization
Members of an organization are able to fully control all databases contained within that organization. Only the owner is allow to access billing information.
To add a member to the current organization:
$ turso org members add $GITHUB_USERNAME
Use the -a flag to add with the admin role.
To list existing members:
$ turso org members list
To remove a member from the current organization:
$ turso org members rm $GITHUB_USERNAME
Invite members to an organization
The owner of an organization can invite others to join. Sending an invitation requires an email address. It can be any email address, not necessarily linked to a GitHub account. To send the invitation:
$ turso org members invite $EMAIL
The recipient is asked to sign in to GitHub and accept the invitation to complete the process. Turso then uses the GitHub account's address for further email notifications.
Use the -a flag to invite with the admin role.
Manage billing
The owner of an organization may manage billing information for the current organization using the following commands:
| Command | Action |
|---|---|
turso plan show | Shows the current payment plan and usage |
turso plan upgrade | Upgrade the current plan (from starter to scaler) |
turso plan select | Select a specific payment plan |
turso org billing | Update credit card information |
A credit card is required to switch to the scaler plan. Credit card information is entered on a per-organization basis. The CLI launches a web browser to manage credit card information for the current organization.
See the website for Turso pricing information.
Platform API auth tokens
The Turso CLI can mint tokens for authentication with the Turso Platform API.
The platform API auth tokens generated by the turso auth api-tokens command
are different in purpose from database auth tokens for client
access. They are not interchangeable.
Mint a platform token
To mint a new token with a given name:
$ turso auth api-tokens mint $TOKEN_NAME
The CLI outputs the string value of the token.
Be sure to copy the token to a safe place immediately after minting. The CLI will not display its value again, and it is not recoverable.
List platform tokens
To list all tokens:
$ turso auth api-tokens list
Revoke a platform token
To revoke a token with a given name:
$ turso auth api-tokens revoke $TOKEN_NAME
Inspect database usage
Total database usage, measured for the purpose of billing, is aggregated across all logical databases associated with an account. Depending on your payment plan, limits are applied to the following usage stats:
- Total amount of storage
- Number of rows read
- Number of rows written
- Total number of database instances (primary and replicas)
- Total number of database locations used
To see a summary for all databases for your account, use the following command:
$ turso plan show
You can get more detailed data about the current monthly usage of a single logical database using the following command:
$ turso db inspect $DB_NAME
It might take up to one minute for the output to reflect recent operations.
You can show usage grouped per instance by running:
$ turso db inspect $DB_NAME --verbose
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
You can also create a new database using the contents of the dump file.
Use libSQL server locally
The Turso CLI can invoke libSQL server for use during local development
instead of a managed Turso database. You must have the sqld binary in your
shell PATH. To start the server on port 8080, run:
$ turso dev
This starts libSQL server 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 local server. 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 client access port 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's safe to delete this folder,
since it can be restored by logging in to the CLI again.