Turso 1.0.34 常用 CLI 命令与工具详解

Turso CLI v1.0.34 全子命令详解：turso dev/db shell SQL 交互与元命令、sqld 独立运行、HTTP 探活等本地能力实测回显逐行照抄；db/auth/config/group/org/plan 等云命令给出实测帮助与未登录门槛报错，云端形态标注需登录前置

TursoTursolibSQL边缘数据库2026/10/18

Turso 1.0.34 常用 CLI 命令与工具详解

目标：系统讲解 Turso CLI v1.0.34 的全部子命令——本地能力（turso dev、turso db shell SQL 交互、sqld 独立运行、HTTP 探活）逐条实测并照抄真实回显，云资源命令（db create/list/show/destroy、auth、group、org、plan 等）给出经官方文档核实的命令形态并 ⚠️ 标注「需 Turso Cloud 账号」前置，实测其未登录门槛报错。所有命令在 Ubuntu 22.04 x86_64 实测环境逐条验证。

一、环境信息

本章是全部实测回显的可复现基准。

  • 操作系统：Ubuntu 22.04（x86_64）
  • Turso CLI：v1.0.34（turso --version 实测回显 turso version v1.0.34；安装过程见《Ubuntu 22.04 安装 Turso 1.0.34 指南》）
  • 随装 libSQL 服务器：sqld 0.24.32 (40c272de 2025-02-14)（/root/.turso/sqld --version 实测回显）
  • 云平台：Turso Cloud（docs.turso.tech 文档口径，2026-10-18 核对）；本文实测环境未登录云端账号，云资源命令一律呈现「帮助文本（实测）+ 未登录门槛报错（实测）+ 官方文档形态说明」
  • 命令输出约定：文末带 ⣾ Connecting to database 的输出是 turso db shell 建立连接时的过程提示行，逐行照抄保留

二、工具概览

Turso CLI 是 Turso 平台的唯一官方命令行入口，单个二进制覆盖四类职责：云端资源管理（auth/db/group/org/plan）、本地开发（dev、db shell 对本地 URL 的连接）、CLI 自维护（config/update）与引导（quickstart/relax）。顶层命令地图（turso --help 实测）：

Turso CLI

Usage:
  turso [command]

Available Commands:
  auth         Authenticate with Turso
  config       Manage your CLI configuration
  db           Manage databases
  dev          starts a local development server for Turso
  group        Manage your database groups
  help         Help about any command
  org          Manage your organizations
  plan         Manage your organization plan
  quickstart   New to Turso? Start here!
  relax        Sometimes you feel like you're working too hard... relax!
  update       Update the CLI to the latest version

Flags:
  -c, --config-path string   Path to the directory with config file
  -h, --help                 help for turso
  -v, --version              version for turso

Use "turso [command] --help" for more information about a command.

命令与账号的关系总览（决定哪些能离线实测、哪些需要登录）：

子命令作用未登录是否可用
turso dev启动本地 libSQL 开发服务器✅ 可用（离线核心）
turso db shell <http(s) URL>SQL 交互 shell（本地/远程 URL）✅ 可用
turso db shell <库名>连接云端数据库❌ 需登录
turso db create/list/show/destroy/...云端数据库生命周期❌ 需登录
turso auth login/signup/logout/token/whoami/api-tokens平台认证与令牌部分可用（logout/logout 查询类需登录）
turso config path/set/cacheCLI 配置多数 ❌ 需登录（set 帮助可看）
turso group / org / plan组织与分组管理❌ 需登录
turso quickstart / relax新手引导 / 彩蛋❌ 需登录（实测均被门槛拦截）
turso updateCLI 自升级✅ 可用

⚠️ 未登录门槛的统一形态（本文多处实测均为此句，不再重复给出）：You are not logged in, please login with turso auth login before running other commands.

三、前置条件

  • 已按《Ubuntu 22.04 安装 Turso 1.0.34 指南》完成安装，turso --version 与 /root/.turso/sqld --version 有正常回显；
  • 交互式 shell（PATH 生效）或使用全路径 /root/.turso/turso；
  • 如需云资源命令，另需 Turso Cloud 账号（https://turso.tech 注册）——本文实测环境刻意不登录，以呈现真实的门槛行为；
  • 可选：curl（用于 sqld HTTP 探活）与 sqlite3（用于直接读取数据文件做对照验证）。

四、全局用法与帮助体系

4.1 版本查询与帮助

turso --version      # 或 turso -v
turso --help         # 顶层帮助，见第二章
turso db --help      # 任意子命令的帮助

⚠️ 注意：turso version（无横杠）不是合法命令，实测报 Error: unknown command "version" for "turso"；旧资料中的 turso version 写法在 v1.0.34 会直接失败。

4.2 全局参数

参数说明
-c, --config-path <目录>指定配置目录（每个子命令的 Global Flags 中均存在）
-h, --help子命令帮助
-v, --version顶层版本；注意 turso dev -v 中 -v 被复用为「显示 sqld 版本」

五、本地开发命令详解（离线核心）

本组命令无需云账号，是 Turso「本地优先」开发体验的主体。

5.1 turso dev：一键本地开发服务器

turso dev 在本机拉起一个与 Turso Cloud 同协议的 libSQL 服务器（内部实际执行 sqld --no-welcome --http-listen-addr 0.0.0.0:8080 -d /tmp/<随机串>tursodev，可用 ps aux | grep sqld 观察到）。帮助与参数（turso dev --help 实测）：

starts a local development server for Turso.

If you're using a libSQL client SDK that supports SQLite database files on the local filesystem, then you might not need this server at all.
Instead, you can use a file: URL with the path to the file you want the SDK to read and write.

Usage:
  turso dev [flags]

Flags:
  -a, --auth-jwt-key-file string   Path to a file with a JWT decoding key used to authenticate clients in the Hrana and HTTP APIs. The key is either a PKCS#8-encoded Ed25519 public key in PEM, or just plain bytes of the Ed25519 public key in URL-safe base64.
  -f, --db-file string             A file name to persist the data of this dev session
  -h, --help                       help for dev
  -p, --port int                   the port to which bind the server (default 8080)
  -v, --version                    sqld version

Global Flags:
  -c, --config-path string   Path to the directory with config file

启动持久化实例（--db-file 指定数据文件）：

turso dev --db-file demo.db

实测启动回显：

sqld listening on port 8080.
Use the following URL to configure your libSQL client SDK for local development:

    http://127.0.0.1:8080

By default, no auth token is required when sqld is running locally. If you want to require authentication, use --auth-jwt-key-file to specify a file containing the JWT key.

Using database file demo.db.

不指定 --db-file 的临时实例：数据存内存，帮助回显明确警示（实测原文）：

This server is using an ephemeral database. Changes will be lost when this server stops.

自定义端口（-p 8081，实测换端口启动并查询）：

turso dev -p 8081 --db-file /tmp/second.db   # 另一终端执行查询
turso db shell http://127.0.0.1:8081 "SELECT 123 AS port_test;"

实测回显：

PORT TEST
123

查看随装 sqld 版本：

turso dev -v

实测回显：

sqld sqld 0.24.32 (40c272de 2025-02-14)

💡 要点：dev 是前台进程，实验时建议 nohup turso dev --db-file demo.db > /tmp/turso-dev.log 2>&1 & 后台运行，日志与启动提示都会写入该文件。

5.2 turso db shell：SQL 交互 shell

语法（turso db shell --help 实测，示例原文照抄）：

Start a SQL shell.
When database-name is provided, the shell will connect the closest replica of the specified database.
When the --instance flag is provided with a specific instance name, the shell will connect to that instance directly.

Usage:
  turso db shell <database-name | replica-url> [sql] [flags]

Examples:
  turso db shell http://127.0.0.1:8080
  turso db shell name-of-my-amazing-db
  turso db shell name-of-my-amazing-db --location yyz
  turso db shell name-of-my-amazing-db --instance a-specific-instance
  turso db shell name-of-my-amazing-db "select * from users;"

Flags:
      --attach strings                 list of database names with attach claim to be added to the token
  -h, --help                           help for shell
      --instance string                Connect to the database at the specified instance.
      --location string                Connect to the database at the specified location.
      --proxy string                   Proxy to use for the connection.
      --remote-encryption-key string   Encryption key (in base64) for accessing encrypted databases on Turso cloud

Global Flags:
  -c, --config-path string   Path to the directory with config file

单条 SQL（参数直传）：

turso db shell http://127.0.0.1:8080 "SELECT 1+1 AS result;"

实测回显：

RESULT
2

多语句批处理（管道输入，逐条执行）：

printf "CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, username TEXT, created_at TEXT);\nINSERT INTO users (username, created_at) VALUES ('alice', '2026-10-18'), ('bob', '2026-10-18'), ('carol', '2026-10-18');\nSELECT * FROM users;\n" | turso db shell http://127.0.0.1:8080

实测回显：

⣾  Connecting to database
ID     USERNAME     CREATED AT
1      alice        2026-10-18
2      bob          2026-10-18
3      carol        2026-10-18

更新与删除批处理（同库继续操作，实测 UPDATE 后同批 SELECT 已见新值，DELETE 后计数变 2）：

printf "UPDATE users SET username='alice2' WHERE id=1;\nSELECT * FROM users;\nDELETE FROM users WHERE id=3;\nSELECT count(*) AS remaining FROM users;\n" | turso db shell http://127.0.0.1:8080

实测回显：

⣾  Connecting to database
ID     USERNAME     CREATED AT
1      alice2       2026-10-18
2      bob          2026-10-18
3      carol        2026-10-18
REMAINING
2

元命令（点命令）：shell 支持 8 个点命令，.help 实测回显：

⣾  Connecting to database

  .dump       Render database content as SQL
  .help       List of all available commands.
  .indexes    List indexes in a table or database
  .mode       Set output mode
  .quit       Exit this program
  .read       Execute commands from a file
  .schema     Show table schemas.
  .tables     List all existing tables in the database.

.tables 实测回显：

⣾  Connecting to database
users

.schema users 实测回显：

⣾  Connecting to database
CREATE TABLE users (id INTEGER PRIMARY KEY, username TEXT, created_at TEXT);

查询本地 dev 服务器的两种探活方式（HTTP 层）：

curl -s http://127.0.0.1:8080/version; echo
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/health

实测回显：

sqld 0.24.32 (40c272de 2025-02-14)
200

⚠️ 注意：turso db shell 的连接目标是「云端库名」或「URL」，不能直接打开本地文件路径。实测 turso db shell /tmp/localdemo.db 报 Error: Binary was compiled with 'CGO_ENABLED=0', go-sqlite3 requires cgo to work. This is a stub；turso db shell file:///tmp/localdemo.db 报 Error: invalid sqld protocol. valid protocols are libsql://, wss://, ws://, https:// and http://。访问本地数据的正确姿势是先 turso dev 再连 http://127.0.0.1:8080（或应用侧 SDK 用 file: URL）。

5.3 sqld：独立运行 libSQL 服务器

~/.turso/sqld 可脱离 turso 直接运行，适合把 libSQL 当独立网络数据库部署。帮助要点（sqld --help 实测节选）：

SQL daemon

Usage:
  sqld [OPTIONS] [COMMAND]

Commands:
  admin-shell
  wal-toolkit
  help         Print this message or the help of the given subcommand(s)

Options:
  -d, --db-path <DB_PATH>
          [env: SQLD_DB_PATH=]
          [default: data.sqld]
      --http-listen-addr <HTTP_LISTEN_ADDR>
          [env: SQLD_HTTP_LISTEN_ADDR=]
          [default: 127.0.0.1:8080]
      --enable-http-console
          Enable a web-based http console served at the /console route

启动并验证（监听 8085，数据目录 /opt/data/demo-sqld）：

nohup /root/.turso/sqld --no-welcome --http-listen-addr 127.0.0.1:8085 --db-path /opt/data/demo-sqld > /tmp/sqld-direct.log 2>&1 &

实测启动日志（节选）：

2026-10-18T13:26:20.609548Z  INFO sqld: listening for incoming user HTTP connection on 127.0.0.1:8085
2026-10-18T13:26:20.613312Z  INFO restore: libsql_server::namespace::meta_store: restoring meta store
2026-10-18T13:26:20.614224Z  INFO libsql_server: Server sending heartbeat to URL <not supplied> every 30s

turso db shell http://127.0.0.1:8085 "SELECT 40+2 AS answer;"

实测回显：

ANSWER
42

5.4 数据持久化与文件形态

turso dev --db-file demo.db 生成的数据文件是标准 SQLite（WAL 模式）三件套，实测目录形态：

-rw-r--r-- 1 root root  4096 Oct 18 12:56 /root/demo.db
-rw-r--r-- 1 root root 32768 Oct 18 12:57 /root/demo.db-shm
-rw-r--r-- 1 root root 12392 Oct 18 12:57 /root/demo.db-wal

持久化已做整机重启级验证：写入 3 行 users 数据 → 完全重启 → 以同一 --db-file 重新 turso dev → 查询数据完整（实测回显与 5.2 建表后查询一致），且 sqlite3 /root/demo.db "SELECT count(*) FROM users;" 实测回显 3，证明数据确实落盘于该文件而非服务器内存。

六、db 子命令详解

turso db 是数据库生命周期管理的核心，共 14 个子命令（turso db --help 实测）：

Manage databases

Usage:
  turso db [command]

Available Commands:
  branch      Create a branch from an existing database.
  config      Manage db config
  create      Create a database.
  destroy     Destroy a database.
  export      Export a database snapshot and its log from Turso to local files.
  import      Import a SQLite database file to Turso.
  inspect     Inspect database.
  list        List databases.
  locations   List available database locations.
  replicate   Replicate a database.
  shell       Start a SQL shell.
  show        Show information from a database.
  tokens      Manage db tokens
  unarchive   Unarchive a database

Flags:
  -h, --help   help for db

Global Flags:
  -c, --config-path string   Path to the directory with config file

Use "turso [command] --help" for more information about a command.

⚠️ 除 6.9 shell（连 URL 时）外，本组命令均操作 Turso Cloud 资源，前置条件：已 turso auth login 登录。以下各命令的帮助文本与门槛报错均为实测照抄；「行为说明」依据官方文档口径（docs.turso.tech/cli），本文不编造云端成功回显。

6.1 db create：创建数据库

帮助（实测，参数表完整照抄）：

Create a database.

Usage:
  turso db create [flags] [database-name]

Flags:
      --csv-separator string              CSV separator character. Must be a single character. (default ",")
      --csv-table-name string             name of the table in the csv file
      --enable-extensions                 Enables experimental support for SQLite extensions.
      --from-csv string                   create the database from a csv file
      --from-db string                    Select another database to copy data from. To use data from a past version of the selected database, see the 'timestamp' flag.
      --from-dump string                  create the database from a local SQLite dump
      --from-dump-url string              create the database from a remote SQLite dump
      --from-file string                  create the database from a local SQLite3-compatible file
      --group string                      create the database in the specified group
  -h, --help                              help for create
      --location string                   Location ID. If no ID is specified, closest location to you is used by default.
      --remote-encryption-cipher string   Cipher to use for database encryption
      --remote-encryption-key string      Encryption key (in base64) for accessing encrypted databases on Turso cloud
      --schema string                     Schema to use for the database
      --size-limit string                 The maximum size of the database in bytes. Values with units are accepted, e.g. 1mb, 256mb, 1gb
      --timestamp string                  Set a point in time in the past to copy data from the selected database. Must be used with the 'from-db' flag. Must be in RFC3339 format like '2023-09-29T10:16:13-03:00'
      --tursodb                           Create the database using TursoDB (MVCC).
      --type string                       Type of the database to create. Possible values: regular, schema. (default "regular")
  -w, --wait                              Wait for the database to be ready to receive requests.

Global Flags:
  -c, --config-path string   Path to the directory with config file

官方形态说明（依据 docs.turso.tech，⚠️ 需登录）：turso db create <name> 在当前组织默认分组创建数据库；--location 缺省自动选最近位置；--from-file 可把本地 SQLite 文件直接推成云端库；--size-limit 支持带单位限额（如 512mb）；--type schema 创建「schema 数据库」供多库共享表结构；--tursodb 选用 MVCC 存储引擎。

实测门槛回显（未登录）：

You are not logged in, please login with turso auth login before running other commands.

6.2 db list：列出数据库

帮助（实测）：

List databases.

Usage:
  turso db list [flags]

Flags:
  -g, --group string    Filter databases by group
  -h, --help            help for list
  -s, --schema string   Filter databases by schema

Global Flags:
  -c, --config-path string   Path to the directory with config file

官方形态（⚠️ 需登录）：输出当前组织全部数据库列表，含库名、所在位置/分组、容量与版本列，支持按分组（-g）与 schema（-s）过滤。实测门槛回显同 6.1。

6.3 db show：查看库详情

帮助（实测）：

Show information from a database.

Usage:
  turso db show <database-name> [flags]

Flags:
      --branches              Show a list of branches for this database.
  -h, --help                  help for show
      --http-url              Show HTTP URL for the database HTTP API.
      --instance-url string   Show URL for the HTTP API of a selected instance of a database. Instance is selected by instance name.
      --instance-urls         Show URL for the HTTP API of all existing instances
      --url                   Show URL for the database HTTP API.

Global Flags:
  -c, --config-path string   Path to the directory with config file

官方形态（⚠️ 需登录）：turso db show <库名> 展示库的 URL、位置、容量等；--url 单独输出 libsql:// 连接串（SDK/Shell 连接用），--http-url 输出 HTTP API 地址，--branches 列出分支。实测门槛回显同 6.1（实测命令 turso db show testdb）。

6.4 db destroy：销毁数据库

帮助（实测）：

Destroy a database.

Usage:
  turso db destroy <database-name> [flags]

Flags:
  -h, --help              help for destroy
      --instance string   Pick a specific database instance to destroy.
      --location string   Pick a database location to destroy.
  -y, --yes               Confirms the destruction of all locations of the database.

Global Flags:
  -c, --config-path string   Path to the directory with config file

官方形态（⚠️ 需登录）：删除云端数据库；多位置库默认会要求二次确认，-y 跳过确认销毁全部位置副本；--instance/--location 可只删单个实例/位置副本。⚠️ 破坏性操作，生产环境建议保留确认流程。

6.5 db locations / replicate / branch：位置与副本体系

db locations 列出可部署的全球位置（⚠️ 需登录，实测门槛回显同 6.1）；帮助（实测）：

List available database locations.

Usage:
  turso db locations [flags]

Flags:
  -h, --help   help for locations

Global Flags:
  -c, --config-path string   Path to the directory with config file

db replicate 为既有库增加只读副本（turso db replicate <database-name> <location-code>，-w/--wait 等待副本就绪）；db branch 从既有库创建分支（turso db branch <source> <target>，支持 --timestamp 回溯时间点、--location 指定位置）。两者帮助文本已实测获取，行为依据官方文档（⚠️ 均需登录）。

6.6 db tokens：数据库访问令牌

帮助（实测）：

Manage db tokens

Usage:
  turso db tokens [command]

Available Commands:
  create      Creates a bearer token to authenticate requests to the database
  invalidate  Rotates the keys used to create and verify database tokens making existing tokens invalid

Flags:
  -h, --help   help for tokens

Global Flags:
  -c, --config-path string   Path to the directory with config file

Use "turso db tokens [command] --help" for more information about a command.

官方形态（⚠️ 需登录）：turso db tokens create <库名> 生成访问该库的 Bearer 令牌（应用直连 libsql:// 时使用）；invalidate 轮换签名密钥使存量令牌全部失效。注意区分：平台 API 凭据用 turso auth token / turso auth api-tokens（见第七章）。

6.7 db import / export：本地文件与云端互转

帮助要点（实测）：

# turso db import --help（节选）
Import a SQLite database file to Turso.

Usage:
  turso db import [filename] [flags]

Flags:
      --group string                      create the database in the specified group
      --remote-encryption-cipher string   Cipher to use for database encryption
      --remote-encryption-key string      Encryption key (in base64) for accessing encrypted databases on Turso cloud
      --tursodb                           Import into a TursoDB (MVCC) database.

# turso db export --help（节选）
Export a database snapshot and its log from Turso to local files.

Usage:
  turso db export <database> [flags]

Flags:
      --output-file string             Specify the output file name (default: <database>.db)
      --overwrite                      Overwrite output file if it exists.
      --with-metadata                  Include metadata in the export.

官方形态（⚠️ 需登录）：import 把本地 SQLite 文件导入为云端库（与 db create --from-file 等效的快捷入口）；export 把云端库快照导出为本地 .db 文件（SQLite 系库的 WAL 帧保存为 <库>.db-wal，MVCC 库的逻辑日志保存为 <库>.db-log，节选帮助原文即此说明），是解除平台锁定的官方通道。

6.8 db inspect / config / unarchive

  • db inspect <库名>（别名 usage）：查看容量与用量统计，--queries 显示查询统计、--verbose 详细输出（⚠️ 需登录）；
  • db config：库级配置三件套——allow-rules（访问允许规则）、attach（跨库 attach 配置）、delete-protection（删除保护）（⚠️ 需登录）；
  • db unarchive <库名>（别名 wakeup）：唤醒已归档库（⚠️ 需登录）。

三者帮助文本均实测获取，形态依据官方文档。

6.9 db shell 连接云端库（⚠️ 需登录）

turso db shell name-of-my-amazing-db 按 5.2 语法连接云端库，未登录实测门槛回显同 6.1。登录后即可对云端库执行与本地完全相同的 SQL 与点命令（5.2 全部实测形态通用）。

七、auth 子命令详解

认证与令牌族，共 6 个子命令（turso auth --help 实测）：

Authenticate with Turso

Usage:
  turso auth [command]

Available Commands:
  api-tokens  Manage your API tokens
  login       Login to the platform.
  logout      Log out currently logged in user.
  signup      Create a new Turso account.
  token       Shows the token used to authenticate you to Turso platform API.
  whoami      Show the currently logged in user.

Flags:
  -h, --help   help for auth

Global Flags:
  -c, --config-path string   Path to the directory with config file

Use "turso auth [command] --help" for more information about a command.

7.1 auth signup / login：注册与登录（⚠️ 需要浏览器或 headless 流程）

帮助（实测）：

# turso auth signup --help
Create a new Turso account.

Usage:
  turso auth signup [flags]

Flags:
      --headless   Give users a link to start the process by themselves. Useful when the CLI can't interact with a web browser.
  -h, --help       help for signup

# turso auth login --help
Login to the platform.

Usage:
  turso auth login [flags]

Flags:
      --headless   Give users a link to start the process by themselves. Useful when the CLI can't interact with a web browser.
  -h, --help       help for login

官方形态说明（依据 docs.turso.tech/cli，本文实测环境未执行登录）：交互终端直接运行 turso auth signup / turso auth login 会给出认证 URL 并尝试打开浏览器完成 OAuth；无浏览器的服务器上用 --headless，CLI 打印链接，复制到本机浏览器完成认证后 CLI 自动收到凭据。凭据保存在 ~/.config/turso/ 配置目录。

7.2 auth whoami / token：身份与平台凭据查询

turso auth whoami 显示当前登录用户（⚠️ 需登录，实测门槛回显同前）；turso auth token 显示平台 API 用的令牌，帮助原文明确提示其与库令牌的分工（实测）：

Shows the token used to authenticate you to Turso platform API.
To authenticate to your databases, use turso db tokens create

Usage:
  turso auth token [flags]

Flags:
  -h, --help   help for token

7.3 auth logout：登出

帮助与未登录实测：

Log out currently logged in user.

Usage:
  turso auth logout [flags]

Flags:
  -a, --all    Invalidate all sessions for the current user
  -h, --help   help for logout

turso auth logout

实测回显：

No user logged in.

💡 说明：logout 是少数未登录也不报错反而给出友好提示的命令；-a/--all 会注销该账号的全部会话（不只当前设备）。

7.4 auth api-tokens：可撤销的长期 API 令牌

帮助（实测）：

API tokens are revocable non-expiring tokens that authenticate holders as the user who created them.
They can be used to implement automations with the turso CLI or the platform API.

Usage:
  turso auth api-tokens [command]

Available Commands:
  list        List API tokens.
  mint        Mint an API token.
  revoke      Revoke an API token.

Flags:
  -h, --help   help for api-tokens

Global Flags:
  -c, --config-path string   Path to the directory with config file

Use "turso auth api-tokens [command] --help" for more information about a command.

官方形态（⚠️ 需登录）：mint <名称> 铸造不自动过期的 API 令牌（CI/自动化场景把 turso config set token <jwt> 或平台 API 的 Bearer 用它），list 列出、revoke <名称> 吊销。

八、config 子命令详解

CLI 自身配置族（turso config --help 实测）：

Manage your CLI configuration

Usage:
  turso config [command]

Available Commands:
  cache       Manage your CLI cache
  path        Get the path to the CLI configuration file
  set         Set a configuration value

Flags:
  -h, --help   help for config

Global Flags:
  -c, --config-path string   Path to the directory with config file
命令语法行为与实测
config pathturso config path查询配置文件路径；⚠️ 实测未登录被门槛拦截（门槛回显同第二章）
config set autoupdateturso config set autoupdate <on|off>开关自动更新；帮助实测：Configure autoupdate behavior / Usage: turso config set autoupdate <on|off> [flags]
config set tokenturso config set token <jwt>以 JWT 方式直接配置凭据（自动化/CI 免交互登录）；帮助实测：Configure the token used by turso
config cache clearturso config cache clear清理本地缓存；⚠️ 实测未登录被门槛拦截

配置落盘位置与文件内容实测见《Ubuntu 22.04 安装 Turso 1.0.34 指南》7.2 节：~/.config/turso/settings.json（实测内容 {"config-path": ""}）与 .turso/ 下的 shell 历史缓存文件。

九、group / org / plan 子命令详解

三者均为纯云端资源管理（⚠️ 全部需登录），本节给实测帮助地图与官方形态说明。

9.1 group：数据库分组（复制组）

Manage your database groups

Usage:
  turso group [command]

Available Commands:
  aws-migration Manage AWS migration of the group
  config        Manage group config
  create        Create a database group
  destroy       Destroy a database group
  list          List databases groups
  locations     Manage your database group locations
  rename        Renames the group
  show          Show information about a group.
  tokens        Manage group tokens
  transfer      Transfers the group to the specified organization
  unarchive     Unarchive a database group

Flags:
  -h, --help   help for group

Global Flags:
  -c, --config-path string   Path to the directory with config file

官方形态（依据 docs.turso.tech）：group 是「共享一组位置的数据库集合」，成员库共享复制拓扑；group create <名> <位置代码...> 建组，locations add/remove 调整组内位置，库创建时用 --group 归入组内。

9.2 org：组织管理

Manage your organizations

Usage:
  turso org [command]

Available Commands:
  audit-logs  Manage organization audit logs
  create      Create a new organization
  db-transfer Transfers a database to another organization
  destroy     Destroy an organization
  invites     Manage your organization invites
  invoice     Manage Invoices
  jwks        [BETA] Manage your organization external JWKS sources
  list        List your organizations
  members     Manage your organization members
  switch      Switch to an organization as the context for your commands.

Flags:
  -h, --help   help for org

Global Flags:
  -c, --config-path string   Path to the directory with config file

官方形态：org switch 切换当前命令上下文的组织（个人账号与企业组织之间），members/invites 管理成员与邀请，audit-logs 审计日志，invoice 发票，jwks（BETA）接入外部 JWKS 密钥源做令牌校验。

9.3 plan：套餐管理

Manage your organization plan

Usage:
  turso plan [command]

Available Commands:
  show        Show your current organization plan

Flags:
  -h, --help   help for plan

Global Flags:
  -c, --config-path string   Path to the directory with config file

官方形态：turso plan show 查看当前组织套餐与用量额度；套餐变更在官网控制台完成（帮助仅保留 show 子命令）。

十、quickstart / relax / update

10.1 turso quickstart：五分钟引导

New to Turso? Start here!

Usage:
  turso quickstart [flags]

Flags:
  -h, --help   help for quickstart

Global Flags:
  -c, --config-path string   Path to the directory with config file

⚠️ 需登录：官方定位是「5 分钟入门引导」，实测未登录被门槛拦截（回显同第二章）。登录后会以交互问答引导完成建库与连接。

10.2 turso relax：彩蛋

Sometimes you feel like you're working too hard... relax!

Usage:
  turso relax [flags]

Flags:
  -h, --help   help for relax

Global Flags:
  -c, --config-path string   Path to the directory with config file

⚠️ 有趣的实测发现：这个官方彩蛋命令同样要求登录（未登录实测被门槛拦截回显同第二章）——它是登录后陪着等迁移时放松的小玩具。

10.3 turso update：CLI 自升级

turso update

实测回显（已是最新版）：

Current version: v1.0.34, latest version: v1.0.34
version v1.0.34 is already latest

无需登录、可离线判断版本差距；有新版本时自动下载覆盖。升级机制与手动多版本并存方案详见《Ubuntu 22.04 安装 Turso 1.0.34 指南》第八章。

十一、注意事项

  1. 版本查询写法：用 turso --version，不要用 turso version（实测报 unknown command）。
  2. 本地文件访问路径：turso db shell 只接受 URL 或云端库名；本地数据走 turso dev + http://127.0.0.1:8080（CGO 限制详见《Ubuntu 22.04 安装 Turso 1.0.34 指南》FAQ Q5）。
  3. dev 是前台进程：长期挂机用 nohup/systemd 托管；--db-file 才落盘，否则停止即失。
  4. 令牌三兄弟分工：平台 API 凭据（auth token）、可撤销自动化令牌（auth api-tokens）、库访问令牌（db tokens create）三者互不通用，别混用。
  5. 破坏性命令：db destroy、group destroy、org destroy 均 -y/--yes 可跳过确认，脚本化时务必核对库名来源。
  6. 错误分层定位：Error: failed to execute SQL: 开头 + SQLite error: 为 SQL 层错误；Post "http://...": dial tcp ... connection refused 为连接层错误（网络/端口未监听）——先分层再排障（实测回显见 5.2 与《安装指南》FAQ Q7）。
  7. shell 历史明文落盘：turso db shell 的执行历史按目标 URL 写在 ~/.config/turso/.turso/.<地址>_shell_history，含敏感 SQL 的会话注意清理。

十二、常见问题（FAQ）

Q1：所有命令都报 You are not logged in...，哪些命令不登录也能用？ 本地能力全部可用：turso dev（含 -v）、turso db shell <http(s) URL>、turso update、各命令 --help、turso auth logout（友好提示 No user logged in.）、turso config set 子命令的帮助。云资源命令（db 资源管理、group/org/plan、quickstart/relax、config path/cache、whoami/token）需要登录。

Q2：turso db create 成功后输出长什么样？ 本文实测环境未注册云端账号，不掌握真实成功回显，为避免误导不作转述；执行形态与参数以上文 6.1 实测帮助表为准，结果形态请以登录后实际输出或官方文档（https://docs.turso.tech/cli ）为准。

Q3：dev 服务器端口被占了怎么办？ 用 -p 换端口（实测 8081 可正常服务，见 5.2），或先 ss -ltnp | grep 8080 找到占用进程处理；独立 sqld 场景改 --http-listen-addr。

Q4：怎么确认数据真的写进了 --db-file 文件？ 三重验证（均实测）：dev 重启后 SELECT 数据仍在；sqlite3 <db-file> "SELECT count(*) FROM <表>;" 直接读文件（5.4 实测回显 3）；ls -la 可见 .db/.db-wal/.db-shm 三件套。

Q5：如何把本地开发库「带走」到云端或另一台机器？ --db-file 文件即标准 SQLite 库，直接复制文件即可迁移；上云用 turso db import <文件> 或 turso db create --from-file（⚠️ 需登录，形态见 6.1/6.7）。

十三、参考链接

  1. Turso CLI 官方文档（命令参考）：https://docs.turso.tech/cli
  2. Turso CLI 仓库与 Release：https://github.com/tursodatabase/turso-cli
  3. libSQL 仓库（sqld 上游）：https://github.com/tursodatabase/libsql
  4. Turso 官网（注册/控制台）：https://turso.tech
  5. 本系列姊妹篇：《Turso 1.0.34 介绍与选型指南》《Ubuntu 22.04 安装 Turso 1.0.34 指南》