Steampipe 2.4.9 常用 CLI 命令详解

目标：把 steampipe 二进制的每个子命令跑一遍——参数、真实回显、退出码、坑。安装与服务基线见《Ubuntu 22.04 安装 Steampipe 2.4.9 指南》，配置语义见《Steampipe 2.4.9 配置参数详解》。

一、环境信息

项目	值
操作系统	Ubuntu 22.04.5 LTS (Jammy Jellyfish)，x86_64
软件版本	Steampipe v2.4.9（内嵌 PostgreSQL 14.19）
实测日期	2026-11-03
运行用户	`admin`（root 被拒绝）
已装插件	hackernews 1.2.0、steampipe 1.1.0（均免凭证）

二、命令总览

$ steampipe --help
Steampipe: query APIs and cloud with SQL. Zero-ETL from 140+ data sources.

Usage:
  steampipe <command> <argument> [flags]

Commands
  completion       Output the command completion script for the specified SHELL
  help             Displays a help page for a command or topic
  login            Log in to Turbot Pipes
  plugin           Manage Steampipe plugins
  query            Execute Steampipe queries
  service          Manage Steampipe services

Flags:
  -h, --help                Help for the command being invoked
      --install-dir string  Steampipe installation directory (default: ~/.steampipe) or use environment variable STEAMPIPE_INSTALL_DIR
  -v, --version             Print version information
      --workspace string    Steampipe workspace profile to use (default: 'default' workspace) or use environment variable STEAMPIPE_WORKSPACE

⚠️ 版本事实：v2.4.9 顶层只有以上 6 个子命令。早期（v0.x）的 benchmark、workspace、database 等子命令已不在本版帮助中——老教程里的 steampipe benchmark 会直接报 unknown command，性能测量请用 query --timing（见 3.3）。

三、steampipe query（查询执行）

3.1 内联 SQL 与查询文件

$ steampipe query "select 1 as hello, version();"
+-------+-----------------------------------------------+
| hello | version                                       |
+-------+-----------------------------------------------+
| 1     | PostgreSQL 14.19 on x86_64-pc-linux-gnu ...   |
+-------+-----------------------------------------------+

.sql 文件作为位置参数传入（实测 --timing 同用）：

$ cat /home/admin/top.sql
select t.id, i.title, i.score from hackernews_top t join hackernews_item i on i.id = t.id order by i.score desc limit 3;

$ steampipe query --timing /home/admin/top.sql
+----------+--------------------------------------------------------------+-------+
| id       | title                                                        | score |
+----------+--------------------------------------------------------------+-------+
| 46187309 | ...                                                          | 41    |
+----------+--------------------------------------------------------------+-------+

Time: 1.3 seconds.

多查询文件用 --multi（按文件分节执行）。

3.2 输出格式与导出

--output 支持 table/json/csv/text（默认 table）：

$ steampipe query --output json "select id, title from hackernews_new limit 2;"
{
 "columns": [
  {
   "name": "id",
   "data_type": "int8"
  },
  {
   "name": "title",
   "data_type": "text"
  }
 ],
 "rows": [
  {
   "id": 50348062,
   "title": "Is hosting an open-source inference engine profitable?"
  },
  {
   "id": 50348109,
   "title": "A LoveLetter to Flash Animation [video]"
  }
 ]
}

CSV 可配分隔符与表头开关（--separator、--header=false）。另有 --export FILE（结果写文件，格式由扩展名推断）、--share（发布到 Turbot Pipes，需登录）、--snapshot FILE（.sps 快照）。

3.3 --timing：Steampipe 特色指标

--timing 不只给耗时，还输出插件内部执行画像（实测节选）：

Execution time: 1.3 seconds
Rows fetched: 5501
Hydrate calls: 5001

Rows fetched/Hydrate calls 直接暴露 API 调用量——排查「为什么这条 SQL 这么慢」先看这两个数（hydrate 次数≈对目标 API 的额外调用次数）。

3.4 交互式控制台与点命令

steampipe query 不带参数进入 REPL，点命令（.help、.inspect、.timing 等）只在 REPL 可用。非交互传点命令实测报错：

$ steampipe query ".inspect hackernews_item"
Warning: query 1 of 1 failed: syntax error at or near "."
$ echo $?
41

管道喂 SQL 也不可行（REPL 需要 TTY）：

$ echo "select 2+2;" | steampipe query
Error: no such device or address

非交互自省改用标准 SQL（实测）：

$ steampipe query "select column_name, data_type from information_schema.columns where table_name='hackernews_item' order by ordinal_position limit 8;"
+-------------+-----------+
| column_name | data_type |
+-------------+-----------+
| id          | bigint    |
| by          | text      |
| descendants | jsonb     |
| ...         | ...       |
+-------------+-----------+

3.5 其他实用参数

参数	用途
`--search-path`	指定非限定表名的 schema 解析顺序
`--query-timeout`	覆盖配置的单查询超时（秒）
`--arg/--var`	查询模板参数（配合 `.query` 模板文件）
`--db`	不启动服务，把 SQL 直接打到外部 Postgres
`--watch`	监听当前目录 `.sql/.query` 变化自动重跑

四、steampipe plugin（插件管理）

子命令：install / list / uninstall / update（plugin --help 实测）。

4.1 install

$ steampipe plugin install hackernews
Installed:
+------------+---------+
| Plugin     | Version |
+------------+---------+
| hackernews | 1.2.0   |
+------------+---------+

支持形式（install --help 原文）：Hub 简名（默认 @latest）、plugin@x.y.z 锁版本、plugin@stream 发布流、org/plugin 第三方组织、本地 tar.gz 路径（离线分发）。安装同时生成默认连接文件 config/hackernews.spc。

⚠️ 实测坑：官方文档常引用的示例插件 stub 在 Hub 已不存在：
$ steampipe plugin install stub
Skipped the following plugin:
Plugin: stub@latest
Reason: Not found
$ echo $?
14

4.2 list / update / uninstall

$ steampipe plugin list
+---------------------------------------------------+---------+----------------------+
| Installed                                         | Version | Connections          |
+---------------------------------------------------+---------+----------------------+
| hub.steampipe.io/plugins/turbot/hackernews@latest | 1.2.0   | hn,hn_all,hackernews |
| hub.steampipe.io/plugins/turbot/steampipe@latest  | 1.1.0   | steampipe            |
+---------------------------------------------------+---------+----------------------+

$ steampipe plugin update hackernews
All plugins up to date!
Plugin        Version   Status
hackernews    v1.2.0    Up to date

$ steampipe plugin uninstall steampipe
Uninstalled plugin:
* turbot/steampipe

The following connection is no longer needed since the associated plugin has been uninstalled and can be safely removed:
  * /home/admin/.steampipe/config/steampipe.spc

update 不带参数更新全部；uninstall 不会自动删连接文件（回显给出待清理清单，实测重装后连接文件自动再生）。

五、steampipe service（服务生命周期）

子命令：start / stop / restart / status。

$ steampipe service start
Started Steampipe service (version: 2.4.9) in workspace "default"
...
Database: steampipe
User: steampipe
Password: ****
Port: 9193
Host(s): localhost, 127.0.0.1, ::1, <本机IP>

$ steampipe service status
Service is running:
+-----------+------------------------------------------+
| Process   | Status                                   |
+-----------+------------------------------------------+
| database  | Running                                  |
| plugin    | Running (plugin manager, 2 subprocesses) |
+-----------+------------------------------------------+

$ steampipe service restart
Steampipe service restarted

$ steampipe service stop
Steampipe service stopped

要点（均实测）：

自动拉起/自动回收：steampipe query "SQL" 会按需启动服务并在查询结束后停止——service status 随即显示 Service is not running。常驻服务用 service start 显式启动或 systemd 托管。
连接信息落盘：运行期写 ~/.steampipe/internal/connection.json（停止后变 {}），psql/BI 按 postgresql://steampipe:***@127.0.0.1:9193/steampipe 接入。
关键启动参数：--database-listen local|network|tailnet（默认 network，会覆盖 default.spc 配置，生产务必显式 local）、--database-password、--database-port、--foreground（systemd Type=simple 适配，见安装篇第十节）、--watch。
status 加 --show-password 明文显示口令；--all 绕过本 workspace 报告所有运行中的服务实例。

$ steampipe login --help
Log in to Turbot Pipes
Usage: steampipe login [flags]
Flags:
      --auth string       The method to use for authentication (token)
      --database string   The database to connect to
      --token string      The token to use for authentication
      --workspace string  The workspace to connect to

用于登录官方云 Turbot Pipes（配合 query --share、--export 上云）。本文实验全程离线/本地，未实测登录流程。

七、steampipe completion（补全）

$ steampipe completion bash > /etc/bash_completion.d/steampipe   # 实测输出 426 行
$ steampipe completion zsh | head -3
#compdef steampipe
compdef _steampipe steampipe

支持 bash/zsh/fish/powershell 四种 SHELL（completion --help）。

八、常用场景操作流

① 即席审计（免凭证）：

steampipe query "select id, title, score from hackernews_new order by score desc limit 5;"

② 跨源 JOIN + 性能画像：

steampipe query --timing /home/admin/top.sql

③ 结果喂给下游脚本：

steampipe query --output json --header=false "select count(*) from hn.hackernews_top;" > /tmp/count.json

④ 服务运维：

steampipe service status --all       # 报告所有运行中的服务实例
steampipe service restart            # 改配置后生效
steampipe service stop --force       # 异常残留强停

⑤ 外部客户端接入（psql 实测，见安装篇第十一节）：任意 Postgres 客户端连 9193 即得全部插件表。

九、常见问题

cannot insert multiple commands into a prepared statement（RC=41）：一次 query 参数只放一条语句；多条分别传参或写多查询文件配 --multi。实测：
```
$ steampipe query "select 1; select 2;"
Warning: query 1 of 1 failed: cannot insert multiple commands into a prepared statement
```
syntax error at or near "."：点命令只能在交互式 REPL 用，非交互改标准 SQL。
Error: no such device or address：REPL 需 TTY，管道输入不适用。
relation "hackernews_show" does not exist：表名以插件实际为准（该插件是 hackernews_show_hn），用 information_schema.tables 列全表名核对。
plugin install stub Not found（RC=14）：Hub 已无 stub，改用公开数据插件验证。
function current_version() does not exist：查版本用 version()；steampipe --version 看 CLI 版本。

十、参考链接

CLI 参考（官方）：https://steampipe.io/docs/reference/cli/overview
Steampipe Hub：https://hub.steampipe.io/plugins
站内：《Steampipe 介绍与选型指南》、《Ubuntu 22.04 安装 Steampipe 2.4.9 指南》、《Steampipe 2.4.9 配置参数详解》、《CloudQuery 6.50 常用 CLI 命令详解》

Steampipe 2.4.9 常用 CLI 命令详解

Steampipe 2.4.9 常用 CLI 命令详解

一、环境信息

二、命令总览

三、steampipe query（查询执行）

3.1 内联 SQL 与查询文件

3.2 输出格式与导出

3.3 --timing：Steampipe 特色指标

3.4 交互式控制台与点命令

3.5 其他实用参数

四、steampipe plugin（插件管理）

4.1 install

4.2 list / update / uninstall

五、steampipe service（服务生命周期）

六、steampipe login（Turbot Pipes）

七、steampipe completion（补全）

八、常用场景操作流

九、常见问题

十、参考链接