Marmot 0.11.1 常用 CLI 命令详解

Marmot 0.11.1 命令行全族实测：assets/search/lineage/glossary/metrics/ingest/runs/apikeys/admin 等 22 个子命令族逐条真实回显，含登录、上下文、输出格式与本地摄取。

MarmotMarmot数据目录Go2026/11/02

Marmot 0.11.1 常用 CLI 命令详解

本文逐族实测 Marmot 0.11.1 的 marmot 命令行：同一二进制兼作服务端与 CLI，共 22 个命令族。assets/search/lineage/glossary/metrics/ingest/runs/apikeys/admin 等命令全部给出真实输入与逐行回显，并实录三个实测踩到的行为陷阱（删除类命令报错但实际生效、runs list 与 runs get 的 ID 字段错位、本地 ingest 的主机名解析）。环境为《Marmot 0.11.1 Docker Compose 部署指南》所建栈（Web 端口 8141，目录内已有 222 个 PostgreSQL 资产）；配置项含义见《Marmot 0.11.1 配置参数详解》；概念见《Marmot 数据目录：介绍与选型指南》。

一、环境与版本信息

项目值
组件Marmot（marmotdata/marmot）
版本v0.11.1（2026-10-11 发布；2026-11-02 经 GitHub releases/latest 重定向实查，官方最新稳定版仍为 v0.11.1，与栈内版本一致）
CLI 二进制GitHub Releases 官方包解出的 marmot（约 88 MB，与服务端同一二进制），marmot version 回显 marmot v0.11.1
目标实例http://localhost:8141（Compose 栈 marmot-0.11.1-stack）
鉴权API Key（admin 签发，--api-key 传入；下文以 $KEY 代指）
官方 CLI 文档marmotdata.io/docs/cli（2026-11-01 查询）

⚠️ 网络说明：版本实查时 GitHub REST API 未认证限流，改用 releases/latest 页面重定向取证（经代理 192.168.1.72:7897 可用），回显见 C1 篇第一节。

二、工具概览

marmot --help 实测回显（2026-11-02，节选命令族清单）：

Marmot is a simple to use Data Catalog.

Usage:
  marmot [command]

Available Commands:
  admin                   Administrative operations
  apikeys                 Manage API keys
  assets                  Manage assets in the data catalog
  completion              Generate the autocompletion script for the specified shell
  config                  Manage Marmot CLI configuration
  context                 Manage Marmot server contexts
  generate-encryption-key Generate a secure encryption key for Marmot
  glossary                Manage glossary terms
  help                    Help about any command
  ingest                  Ingest data from sources into Marmot
  lineage                 View asset lineage
  login                   Authenticate with a Marmot instance via browser
  logout                  Remove cached authentication token
  metrics                 View catalog metrics
  operator                Run the Marmot Kubernetes operator
  run                     Start an instance of the Marmot Server
  runs                    View pipeline runs
  search                  Search across assets, glossary, teams, and users
  service-accounts        Manage service accounts
  teams                   View teams
  users                   View users
  version                 Print Marmot version information

Flags:
      --api-key string   API key for authentication
      --config string    config file (default is ./config.yaml)
  -h, --help             help for marmot
      --host string      Marmot API host (default: http://localhost:8080)
  -o, --output string    Output format: table, json, yaml (default: table)

按用途分族：

命令族子命令用途
assetslist / get / search / summary / owners / tags add·remove / delete资产查改删
search（直接跟查询词）跨资产/术语/团队/用户的统一搜索
lineageget血缘图
glossarylist / get / create / update / delete / search业务术语表
metricssummary / by-type / by-provider / top-assets / top-queries目录运营指标
ingest（本地运行摄取）从数据源拉元数据写入目录
runslist / get / entities摄取管道运行记录
users / teamslist / get / me 等用户与团队（只读）
apikeyscreate / list / delete个人 API Key
service-accountscreate / get / list / delete / apikeys服务账号（自动化身份）
adminreindex / reindex-status搜索索引管理
config / contextlist / get / set / init / use / deleteCLI 自身配置与多实例上下文
login / logout—浏览器 OAuth 登录取 token
run / operator—启动服务端 / K8s 算子（见 C1 与 B2）
generate-encryption-key / version / completion—工具类

全局参数四个：--host（目标实例，默认 http://localhost:8080）、--api-key、--config（默认 ./config.yaml）、-o table|json|yaml。

三、前置条件

3.1 获取 CLI

官方三渠道（A1 篇部署形态节，2026-11-01 查询）：brew install marmot、curl -fsSL get.marmotdata.io | sh、GitHub Releases 下载二进制。本环境用 Releases 二进制，实测：

$ ./bin/marmot version
marmot v0.11.1

3.2 鉴权与 CLI 自身配置

三种方式，任选其一（本文示例统一显式传 --api-key）：

  1. API Key：--api-key mrmt_u_xxx（签发见 B2 篇第五节或本文 4.9）；
  2. 浏览器登录：marmot login <url> 走 OAuth 取 token 缓存进上下文（要求服务端设置 server.root_url，见 C1 篇 5.1）；
  3. CLI 配置文件：marmot config set 持久化 host/api_key。实测 marmot config list 回显：
$ ./bin/marmot config list
host = http://localhost:8141
api_key = ****
output = table
current_context = localhost:8141

持久化位置实测为 ~/.config/marmot/config.yaml（宿主用户家目录），内容（密钥打码）：

api_key: mrmt_u_***
current_context: localhost:8141
host: http://localhost:8141
output: table

注意区分：这个文件是 CLI 自身设置；--config ./config.yaml 指向的是服务端配置文件（C1 篇第三节），两者路径规则不同，别混淆。

config get/set 与 context list/use 实测：

$ ./bin/marmot config get host --host http://localhost:8141 --api-key "$KEY"
http://localhost:8141
$ ./bin/marmot config set host http://localhost:8141 --host http://localhost:8141 --api-key "$KEY"
Set host = http://localhost:8141
$ ./bin/marmot context list --host http://localhost:8141 --api-key "$KEY"
* localhost:8141            http://localhost:8141  (no token)
$ ./bin/marmot context use localhost:8141 --host http://localhost:8141 --api-key "$KEY"
Switched to context "localhost:8141"

context 用于多实例切换（每个实例一个上下文，可各自缓存 token）；config init 是交互式初始化，脚本场景直接用 config set。

四、各命令族详解（实测）

以下命令均在宿主执行，统一带 --host http://localhost:8141 --api-key "$KEY"（回显逐行照抄，ANSI 色码略）。

4.1 assets：资产查改删

list（分页 + 三类过滤：--types/--providers/--tags）：

$ marmot assets list --types Table --tags demo --limit 2 --host http://localhost:8141 --api-key "$KEY"
┌──────────────────────────────────────┬───────────┬───────┬────────────┬────────────────┐
│                  ID                  │   NAME    │ TYPE  │ PROVIDERS  │      TAGS      │
├──────────────────────────────────────┼───────────┼───────┼────────────┼────────────────┤
│ fe75479b-5a7f-41dc-8447-1ed1f6b1e21c │ pg_amproc │ Table │ PostgreSQL │ demo, postgres │
│ 131ddb7e-1926-4228-b939-2b884937c72f │ pg_am     │ Table │ PostgreSQL │ demo, postgres │
└──────────────────────────────────────┴───────────┴───────┴────────────┴────────────────┘

Showing 2 of 142 assets

get（按资产 ID）：

$ marmot assets get 6a145b34-2156-4ac2-b110-e0f4a3023ae9 --host http://localhost:8141 --api-key "$KEY"
┌─────────────┬─────────────────────────────────────────────────┐
│    FIELD    │                      VALUE                      │
├─────────────┼─────────────────────────────────────────────────┤
│ ID          │ 6a145b34-2156-4ac2-b110-e0f4a3023ae9            │
│ Name        │ orders                                          │
│ Type        │ Table                                           │
│ Providers   │ PostgreSQL                                      │
│ Description │ PostgreSQL table public.orders in database shop │
│ Tags        │ demo, postgres                                  │
│ MRN         │ mrn://table/postgresql/orders                   │
│ Created     │ 2026-11-01T16:02:28.43326Z                      │
│ Updated     │ 2026-11-01T16:08:20.230376Z                     │
└─────────────┴─────────────────────────────────────────────────┘

search（资产域内模糊匹配）与 summary（按类型/来源/标签计数）：

$ marmot assets search orders --host http://localhost:8141 --api-key "$KEY"
┌──────────────────────────────────────┬─────────────┬───────┬────────────┬────────────────┐
│                  ID                  │    NAME     │ TYPE  │ PROVIDERS  │      TAGS      │
├──────────────────────────────────────┼─────────────┼───────┼────────────┼────────────────┤
│ ce59567a-7cf8-48f8-ab76-3b236a1038e9 │ order_items │ Table │ PostgreSQL │ demo, postgres │
│ 6a145b34-2156-4ac2-b110-e0f4a3023ae9 │ orders      │ Table │ PostgreSQL │ demo, postgres │
└──────────────────────────────────────┴─────────────┴───────┴────────────┴────────────────┘

Showing 2 of 2 results

$ marmot assets summary --host http://localhost:8141 --api-key "$KEY"
Assets by Type:
┌──────────┬───────┐
│   TYPE   │ COUNT │
├──────────┼───────┤
│ Database │ 3     │
│ Table    │ 142   │
│ View     │ 77    │
└──────────┴───────┘

owners（资产负责人）与 tags add/remove：

$ marmot assets owners 6a145b34-2156-4ac2-b110-e0f4a3023ae9 --host http://localhost:8141 --api-key "$KEY"
No owners found.
$ marmot assets tags add 6a145b34-2156-4ac2-b110-e0f4a3023ae9 cli-tag --host http://localhost:8141 --api-key "$KEY"
Tag "cli-tag" added to asset 6a145b34-2156-4ac2-b110-e0f4a3023ae9.
$ marmot assets get 6a145b34-2156-4ac2-b110-e0f4a3023ae9 --host http://localhost:8141 --api-key "$KEY" | grep Tags
│ Tags        │ demo, postgres, cli-tag                         │
$ marmot assets tags remove 6a145b34-2156-4ac2-b110-e0f4a3023ae9 cli-tag --host http://localhost:8141 --api-key "$KEY"
Tag "cli-tag" removed from asset 6a145b34-2156-4ac2-b110-e0f4a3023ae9.

delete（-y 跳过确认）——注意实测怪癖，见第五节陷阱一：

$ marmot assets delete 30166078-b9f2-4921-8a31-e4c90dd8bcfa -y --host http://localhost:8141 --api-key "$KEY"
Error: marmot: Asset not found
$ marmot assets get 30166078-b9f2-4921-8a31-e4c90dd8bcfa --host http://localhost:8141 --api-key "$KEY"
Error: marmot: Asset not found

资产确实已删除（后续摄取重建后以新 ID 0f6fe940-... 回到目录），但命令退出信息不可信，删除后必须用 get/list 复核。

4.2 search：统一搜索

跨资产/术语/团队/用户四类对象，--types 过滤、--limit/--offset 分页：

$ marmot search GMV --types glossary --host http://localhost:8141 --api-key "$KEY"
┌──────────────────────────────────────┬──────┬──────────┬─────────────────────────────┐
│                  ID                  │ NAME │   TYPE   │         DESCRIPTION         │
├──────────────────────────────────────┼──────┼──────────┼─────────────────────────────┤
│ 67c61f00-a3de-42b7-90b3-d814a4cfa490 │ GMV  │ glossary │ 成交总额，orders.total 之和 │
└──────────────────────────────────────┴──────┴──────────┴─────────────────────────────┘

Showing 1 of 0 results

（Showing 1 of 0 results 的总数位恒为 0，是服务端未回传 total 的显示缺陷，不影响结果。）脚本场景用 -o json，实测节选：

$ marmot search orders -o json --host http://localhost:8141 --api-key "$KEY"
{
  "facets": {
    "asset_types": [],
    "providers": [],
    "tags": []
  },
  "limit": 20,
  "results": [
    {
      "description": "PostgreSQL table public.orders in database shop",
      "id": "6a145b34-2156-4ac2-b110-e0f4a3023ae9",
      ...

4.3 lineage：血缘图

lineage get <asset-id> [--depth N]，节点以 MRN 标识：

$ marmot lineage get 6a145b34-2156-4ac2-b110-e0f4a3023ae9 --depth 2 --host http://localhost:8141 --api-key "$KEY"
Lineage for asset 6a145b34-2156-4ac2-b110-e0f4a3023ae9

Nodes:
┌────────────────────────────────┬──────────┬────────┬───────┐
│               ID               │   TYPE   │  NAME  │ DEPTH │
├────────────────────────────────┼──────────┼────────┼───────┤
│ mrn://table/postgresql/orders  │ Table    │ orders │ 0     │
│ mrn://database/postgresql/shop │ Database │ shop   │ -1    │
└────────────────────────────────┴──────────┴────────┴───────┘

Edges:
┌────────────────────────────────┬───────────────────────────────┬──────────┐
│             SOURCE             │            TARGET             │   TYPE   │
├────────────────────────────────┼───────────────────────────────┼──────────┤
│ mrn://database/postgresql/shop │ mrn://table/postgresql/orders │ CONTAINS │
└────────────────────────────────┴───────────────────────────────┴──────────┘

2 nodes, 1 edges

DEPTH 负数=上游、正数=下游；CONTAINS 边是摄取自动产生的库→表包含关系，跨源加工血缘需经 OpenLineage 事件（POST /api/v1/lineage）补充。

4.4 glossary：业务术语表

create（--name/--definition 必填，--description/--parent-id 可选）、list、get、search、update、delete（交互确认）实测串：

$ marmot glossary create --name AOV --definition "客单价，orders.total 均值" --host http://localhost:8141 --api-key "$KEY"
Glossary term created: AOV (ID: 35750cd3-a3cb-43e8-b6ed-b656b99f6afc)

$ marmot glossary list --host http://localhost:8141 --api-key "$KEY"
┌──────────────────────────────────────┬──────┬─────────────────────────────┐
│                  ID                  │ NAME │         DEFINITION          │
├──────────────────────────────────────┼──────┼─────────────────────────────┤
│ 35750cd3-a3cb-43e8-b6ed-b656b99f6afc │ AOV  │ 客单价，orders.total 均值   │
│ 67c61f00-a3de-42b7-90b3-d814a4cfa490 │ GMV  │ 成交总额，orders.total 之和 │
└──────────────────────────────────────┴──────┴─────────────────────────────┘

Showing 2 of 2 terms

$ marmot glossary get 67c61f00-a3de-42b7-90b3-d814a4cfa490 --host http://localhost:8141 --api-key "$KEY"
┌────────────────┬──────────────────────────────────────┐
│     FIELD      │                VALUE                 │
├────────────────┼──────────────────────────────────────┤
│ ID             │ 67c61f00-a3de-42b7-90b3-d814a4cfa490 │
│ Name           │ GMV                                  │
│ Definition     │ 成交总额，orders.total 之和          │
│ Description    │                                      │
│ Parent Term ID │                                      │
│ Created        │ 2026-11-01T16:03:22.444788Z          │
│ Updated        │ 2026-11-01T16:03:22.444788Z          │
└────────────────┴──────────────────────────────────────┘

$ marmot glossary search GMV --host http://localhost:8141 --api-key "$KEY"
（表格同 4.2 的 search --types glossary，此处略）

delete 无 -y 参数，只有交互确认；管道喂 y 可行，但会触发第五节陷阱一（报错而实际已删）。用完整 UUID 删除刚建术语的成功样本：

$ printf 'y\n' | marmot glossary delete 43019901-684d-4a1b-95e3-f853cb47da3a --host http://localhost:8141 --api-key "$KEY"
Are you sure you want to delete glossary term 43019901-684d-4a1b-95e3-f853cb47da3a? (y/N): Glossary term 43019901-684d-4a1b-95e3-f853cb47da3a deleted.

传截断的 ID 则得到 500 而非 400（服务端日志实录）：

$ printf 'y\n' | marmot glossary delete 35750cd3 --host http://localhost:8141 --api-key "$KEY"
Are you sure you want to delete glossary term 35750cd3? (y/N): Error: marmot: Internal server error

{"level":"error","error":"getting glossary term: ERROR: invalid input syntax for type uuid: \"35750cd3\" (SQLSTATE 22P02)","id":"35750cd3","time":"2026-11-02T00:51:55Z","message":"Failed to delete glossary term"}

结论：删除类命令一律传完整 UUID。

4.5 metrics：目录运营指标

五个子命令：summary（总量+按类型）、by-type、by-provider、top-assets（--start/--end RFC3339、--limit，默认近 30 天 Top10）、top-queries。实测：

$ marmot metrics summary --host http://localhost:8141 --api-key "$KEY"
Total Assets: 222

┌──────────┬───────┐
│   TYPE   │ COUNT │
├──────────┼───────┤
│ Database │ 3     │
│ Table    │ 142   │
│ View     │ 77    │
└──────────┴───────┘

$ marmot metrics top-assets --host http://localhost:8141 --api-key "$KEY"
┌────────┬───────┬───────┐
│  NAME  │ TYPE  │ VIEWS │
├────────┼───────┼───────┤
│ orders │ Table │ 2     │
└────────┴───────┴───────┘

$ marmot metrics top-queries --host http://localhost:8141 --api-key "$KEY"
┌───────┬───────┐
│ QUERY │ COUNT │
└───────┴───────┘

top-queries 空表是因为尚无用户搜索记录沉淀（指标采集有周期）；top-assets 的浏览数来自 UI 访问埋点（orders 被点开过 2 次）。注意 summary/metrics 读数来自 5 分钟一次的统计刷新任务（C1 篇 5.3 日志里的 asset-statistics-refresh interval=300000），刚做完增删时读数会滞后。

4.6 ingest：本地摄取

marmot ingest -c <yaml> 在运行 CLI 的机器上拉起数据源插件、直连源库抓元数据再写入目标实例（与服务端调度管道互补：服务端管道见 B2 篇第七节）。摄取文件 ingest2.yaml 实测内容：

name: shop-postgres
runs:
  - postgresql:
      host: postgres
      port: 5432
      user: marmot
      password: "q1w2e3r4"
      ssl_mode: disable
      tags:
        - demo
        - postgres

第一次在宿主直跑失败（主机名 postgres 只在栈内网络可解析，实测回显）：

$ marmot ingest -c ingest2.yaml --host http://localhost:8141 --api-key "$KEY"
Pipeline: shop-postgres

📊 postgresql
--------------
  Starting run...
  ✅ Run started (ID: 4cc5d9c7-b160-4c4b-acc5-58cbcbebe423)
  Discovering assets...
  ❌ Discovery failed: rpc error: code = Unknown desc = initializing database connection: pinging database: failed to connect to `user=marmot database=postgres`: hostname resolving error: lookup postgres on 127.0.0.53:53: server misbehaving
Error: rpc error: code = Unknown desc = initializing database connection: pinging database: failed to connect to `user=marmot database=postgres`: hostname resolving error: lookup postgres on 127.0.0.53:53: server misbehaving

失败运行同样落库（runs list 里可见 failed 记录）。改在栈内网络执行同一命令（compose 对象操作，与 B2 篇 docker compose exec 同法），把摄取文件送进去后成功：

$ docker compose exec -T marmot sh -c 'cat > /tmp/ingest.yaml' < ingest2.yaml
$ docker compose exec -T marmot sh -c 'marmot ingest -c /tmp/ingest.yaml --host http://localhost:8080 --api-key '"$KEY"
  ~ lineage.CONTAINS.mrn://database/postgresql/shop -> mrn://view/postgresql/pg_views
  ~ lineage.CONTAINS.mrn://database/postgresql/shop -> mrn://table/postgresql/customers
  ~ lineage.CONTAINS.mrn://database/postgresql/shop -> mrn://table/postgresql/order_items
  ~ lineage.CONTAINS.mrn://database/postgresql/shop -> mrn://table/postgresql/orders
  ✅ Assets synced: 1 created, 501 updated, 0 deleted
  ✅ Run completed in 2.7101171s

Assets: 1 created, 501 updated
Lineage: 499 updated

✅ All operations completed successfully

要点：ingest 的插件二进制会下载到运行 CLI 的用户 ~/.marmot/plugins/cache（宿主首次执行时实测下载了全量核心插件，耗时数分钟；服务端进程则用自己家目录的缓存，见 B2 篇第六节）；-d/--destroy 会删除该管道的全部资源并要确认，慎用。

4.7 runs：管道运行记录

runs list（表格）/ runs get <id> / runs entities <id> --limit N。实测表格：

$ marmot runs list --host http://localhost:8141 --api-key "$KEY"
┌──────────────────────────────────────┬───────────────┬────────────┬───────────┬─────────────────────────────┬─────────────────────────────┐
│                  ID                  │   PIPELINE    │   SOURCE   │  STATUS   │           STARTED           │          COMPLETED          │
├──────────────────────────────────────┼───────────────┼────────────┼───────────┼─────────────────────────────┼─────────────────────────────┤
│ a6858eb9-448d-4a92-9626-4b8afd5de10d │ shop-postgres │ postgresql │ completed │ 2026-11-02T00:57:05.810468Z │ 2026-11-02T00:57:08.515114Z │
│ 4cc5d9c7-b160-4c4b-acc5-58cbcbebe423 │ shop-postgres │ postgresql │ failed    │ 2026-11-02T00:56:27.593399Z │ 2026-11-02T00:56:27.68816Z  │
│ b3a0901d-b03e-4529-8654-dd5154d96f7d │ shop-postgres │ postgresql │ completed │ 2026-11-02T00:22:34.987198Z │ 2026-11-02T00:22:37.489777Z │
│ d046b753-cf0c-4349-b544-858bf888f442 │ shop-postgres │ postgresql │ failed    │ 2026-11-02T00:22:10.433719Z │ 2026-11-02T00:22:10.493762Z │
│ f981d88f-6120-4e76-871c-e19ddad9a214 │ shop-postgres │ postgresql │ completed │ 2026-11-01T16:08:19.061502Z │ 2026-11-01T16:08:20.716042Z │
│ dcc81816-709a-41af-8941-f4bec79f4b95 │ shop-postgres │ postgresql │ completed │ 2026-11-01T16:02:27.06232Z  │ 2026-11-01T16:02:29.91096Z  │
└──────────────────────────────────────┴───────────────┴────────────┴───────────┴─────────────────────────────┴─────────────────────────────┘

陷阱二：拿表格里任何 ID 去 runs get 都会 404——

$ marmot runs get a6858eb9-448d-4a92-9626-4b8afd5de10d --host http://localhost:8141 --api-key "$KEY"
Error: marmot: [GET /api/v1/runs/{id}] getRunsID (status 404): {}

-o json 揭示每条运行其实有两个 UUID：id（内部主键，runs get 要的就是它）与 run_id（表格 ID 列显示的外显号）：

$ marmot runs list -o json --host http://localhost:8141 --api-key "$KEY"
b3b4dd4c-f004-46f3-b885-eee2e53f688a | run_id: a6858eb9-448d-4a92-9626-4b8afd5de10d | completed | 2026-11-02T00:57:05
1258a0a0-3dbe-4259-8b9d-d0aa0794b57b | run_id: 4cc5d9c7-b160-4c4b-acc5-58cbcbebe423 | failed    | 2026-11-02T00:56:27
994abd79-d407-4046-a775-9c9d777a2bcc | run_id: b3a0901d-b03e-4529-8654-dd5154d96f7d | completed | 2026-11-02T00:22:34
（原输出为 JSON，此处按 id | run_id | status | started 整理展示）

用内部 id 即成功：

$ marmot runs get b3b4dd4c-f004-46f3-b885-eee2e53f688a --host http://localhost:8141 --api-key "$KEY"
┌────────────────┬──────────────────────────────────────┐
│     FIELD      │                VALUE                 │
├────────────────┼──────────────────────────────────────┤
│ Run ID         │ a6858eb9-448d-4a92-9626-4b8afd5de10d │
│ Pipeline       │ shop-postgres                        │
│ Source         │ postgresql                           │
│ Status         │ completed                            │
│ Started        │ 2026-11-02T00:57:05.810468Z          │
│ Completed      │ 2026-11-02T00:57:08.515114Z          │
│ Assets Created │ 1                                    │
│ Assets Updated │ 501                                  │
│ Assets Deleted │ 0                                    │
│ Errors         │ 0                                    │
│ Created By     │ Admin User                           │
└────────────────┴──────────────────────────────────────┘

$ marmot runs entities b3b4dd4c-f004-46f3-b885-eee2e53f688a --limit 2 --host http://localhost:8141 --api-key "$KEY"
┌─────────┬───────────────────────────────────────────────────────────────────────────────────────────┬──────────────────────────────────────────────────────────────────────┬─────────┐
│  TYPE   │                                            MRN                                            │                                 NAME                                 │ STATUS  │
├─────────┼───────────────────────────────────────────────────────────────────────────────────────────┼──────────────────────────────────────────────────────────────────────┼─────────┤
│ lineage │ mrn://lineage/contains/mrn:--database-postgresql-shop->mrn:--table-postgresql-orders      │ mrn://database/postgresql/shop -> mrn://table/postgresql/orders      │ updated │
│ lineage │ mrn://lineage/contains/mrn:--database-postgresql-shop->mrn:--table-postgresql-order_items │ mrn://database/postgresql/shop -> mrn://table/postgresql/order_items │ updated │
└─────────┴───────────────────────────────────────────────────────────────────────────────────────────┴──────────────────────────────────────────────────────────────────────┴─────────┘

Showing 2 of 721 entities

4.8 users / teams / apikeys / service-accounts：身份与访问

$ marmot users me --host http://localhost:8141 --api-key "$KEY"
┌──────────┬──────────────────────────────────────┐
│  FIELD   │                VALUE                 │
├──────────┼──────────────────────────────────────┤
│ ID       │ b8c1d2dc-74a9-457c-8a64-eba9c3e77fa6 │
│ Username │ admin                                │
│ Name     │ Admin User                           │
│ Active   │ true                                 │
│ Roles    │ admin                                │
│ Created  │ 2026-11-01T15:33:49.325575Z          │
└──────────┴──────────────────────────────────────┘

$ marmot users list --host http://localhost:8141 --api-key "$KEY"
┌──────────────────────────────────────┬──────────┬────────────┬────────┬───────┐
│                  ID                  │ USERNAME │    NAME    │ ACTIVE │ ROLES │
├──────────────────────────────────────┼──────────┼────────────┼────────┼───────┤
│ b8c1d2dc-74a9-457c-8a64-eba9c3e77fa6 │ admin    │ Admin User │ true   │ admin │
└──────────────────────────────────────┴──────────┴────────────┴────────┴───────┘

Showing 1 of 1 users

$ marmot teams list --host http://localhost:8141 --api-key "$KEY"
┌────┬──────┬─────────────┐
│ ID │ NAME │ DESCRIPTION │
└────┴──────┴─────────────┘

Showing 0 of 0 teams

apikeys 三件套完整生命周期实测（create <name>，密钥只显示一次；delete <id> -y 有跳过确认参数，删除信息干净可信）：

$ marmot apikeys create cli-demo --host http://localhost:8141 --api-key "$KEY"
API key created successfully.

  Name: cli-demo
  Key:  mrmt_u_vpmI-9rHBIi5qE8sIyD12eNTXt9p3FaOgmV0zwzIx8c=

Save this key — it won't be shown again.

$ marmot apikeys list --host http://localhost:8141 --api-key "$KEY"
┌──────────────────────────────────────┬───────────┬─────────────────────────────┬─────────────────────────────┐
│                  ID                  │   NAME    │           CREATED           │          LAST USED          │
├──────────────────────────────────────┼───────────┼─────────────────────────────┼─────────────────────────────┤
│ db19b542-b54a-40a8-8ef8-70bb70abe7b9 │ cli-demo  │ 2026-11-02T00:49:39.204257Z │ never                       │
│ 37dabeb0-c80c-47e7-9055-0c44b00729e5 │ docs-test │ 2026-11-01T15:42:01.907402Z │ 2026-11-02T00:49:39.283014Z │
└──────────────────────────────────────┴───────────┴─────────────────────────────┴─────────────────────────────┘

$ marmot apikeys delete db19b542-b54a-40a8-8ef8-70bb70abe7b9 -y --host http://localhost:8141 --api-key "$KEY"
API key db19b542-b54a-40a8-8ef8-70bb70abe7b9 deleted.

service-accounts（自动化身份，--roles 逗号分隔角色 ID）创建/列表实测：

$ marmot service-accounts create --name ci-demo --description "CLI 实测" --host http://localhost:8141 --api-key "$KEY"
Service account created.

  ID:   6fe76504-b45b-4035-96b4-3f937f752799
  Name: ci-demo

$ marmot service-accounts list --host http://localhost:8141 --api-key "$KEY"
┌──────────────────────────────────────┬─────────┬────────┬───────┬─────────────────────────────┐
│                  ID                  │  NAME   │ ACTIVE │ ROLES │           CREATED           │
├──────────────────────────────────────┼─────────┼────────┼───────┼─────────────────────────────┤
│ 6fe76504-b45b-4035-96b4-3f937f752799 │ ci-demo │ true   │       │ 2026-11-02T00:49:39.358233Z │
└──────────────────────────────────────┴─────────┴────────┴───────┴─────────────────────────────┘

service-accounts delete 同样只有交互确认且触发陷阱一（报 Service account not found 但实际已删，复核 list 为空）。服务账号建好后可用 service-accounts apikeys 子族给机器身份签发长期密钥。

4.9 admin / login / generate-encryption-key：管理与工具

admin reindex-status 检查搜索索引后端与重建状态（本环境未配 Elasticsearch，实测）：

$ marmot admin reindex-status --host http://localhost:8141 --api-key "$KEY"
ES Configured: false
Running:       false
$ marmot admin reindex --host http://localhost:8141 --api-key "$KEY"
Error: marmot: Elasticsearch is not configured

（含义与 ES 配置见 C1 篇 5.5。）

login 是浏览器 OAuth 流程：无有效缓存 token 时打开浏览器登录，token 按实例上下文缓存 24 小时，并注册进 Docker 凭据存储（供 oras/crane 推送插件制品）。无浏览器场景用 --no-launch-browser 打印登录 URL 人工完成，实测：

$ marmot login http://localhost:8141 --no-launch-browser
Open this URL in a browser to sign in to localhost:8141:

http://localhost:8141/oauth/authorize?response_type=code&client_id=e679bf94-25e3-4daa-8799-79a663d5abea&redirect_uri=http%3A%2F%2Flocalhost%3A40999%2Fcallback&state=...&code_challenge=...&code_challenge_method=S256&scope=openid

If the browser runs on another machine, paste the URL it lands on here and press enter.

（URL 中 state/code_challenge 参数为随机值。命令会阻塞等待粘贴回调 URL——实测 8 秒超时终止；前提条件：服务端必须已设 server.root_url，否则授权链接不可用，见 C1 篇 5.1。logout 清除缓存 token，未在本环境演示以免破坏已有上下文。）

generate-encryption-key 生成服务端凭据加密密钥（32 字节 base64），实测输出：

$ marmot generate-encryption-key

  Your encryption key:

    izSoAhS2bJp1EqgcJA7BEIQz1dt6NIfdc0ERuuupLnk=

  Set it as an environment variable:

    export MARMOT_SERVER_ENCRYPTION_KEY="izSoAhS2bJp1EqgcJA7BEIQz1dt6NIfdc0ERuuupLnk="

  Store this key somewhere safe — losing it means losing access
  to encrypted credentials. See https://marmotdata.io/docs/Deploy
  for full configuration options.

密钥在「Your encryption key:」之后的缩进行（多行说明文本，勿直接 tail -1，B2 篇排障二）。

4.10 run / operator / completion

  • marmot run：以前台方式启动 Marmot 服务端实例（配置分层与全部参数见 C1 篇；B2 篇的编排形态即调用同一入口）；
  • marmot operator：Kubernetes 算子控制器，把 Run CRD 调和成 Job/CronJobs（本环境非 K8s，未实测；子参数 --marmot-url/--image/--namespace/--leader-elect 等见 operator --help）；
  • marmot completion：生成 bash/zsh/fish/powershell 自动补全脚本，一行 source <(marmot completion bash) 即可。

五、注意事项（实测陷阱）

陷阱一：删除类命令报错但实际已删。 assets delete、glossary delete、service-accounts delete 实测存在「服务端删除已成功、CLI 却以 not found 报错退出」的现象（复核 get/list 对象均已消失；同族 apikeys delete 及另一次 glossary delete 则正常返回 deleted.）。脚本里不要依赖这些命令的退出信息判断成败，删除后一律 get/list 复核。

陷阱二：runs list 表格 ID ≠ runs get 所需 ID。 表格显示的是外显 run_id，runs get/runs entities 要的是 JSON 里的内部 id（4.7 实测 404 与成功对照）。自动化取 ID 用 -o json。

陷阱三：ingest 在谁机器上跑，就用谁的网络和插件缓存。 数据源主机名必须在运行 CLI 的机器上可解析（宿主直跑失败、栈内执行成功，4.6 对照）；首次执行会向运行用户的 ~/.marmot/plugins/cache 下载核心插件，耗时分钟级。

其他：

  • search/assets search 表格的 Showing N of 0 results 总数恒 0（服务端未回传 total），计数以返回行数为准；
  • metrics/assets summary 读数有 5 分钟统计缓存（asset-statistics-refresh），增删资产后短暂不一致属正常（4.5）；
  • API Key 仅创建时明文显示一次（4.8），丢失只能重签；
  • 表格输出含 Unicode 框线，管道处理请用 -o json|yaml。

六、常见问题

6.1 每条命令都带 --host/--api-key 太长？

marmot config set host http://localhost:8141 与 config set api_key <key> 持久化（3.2，写入 ~/.config/marmot/config.yaml），或 marmot login 用上下文缓存 token；之后命令可裸跑。

6.2 CLI 与 REST API、MCP 怎么分工？

CLI 覆盖日常查询/管理/本地摄取（本文）；REST API 面更大（OpenAPI 规范见实例 /swagger/index.html，管道管理、批量写入等走 API，B2 篇大量示例）；MCP 端点 /api/v1/mcp 供 AI 代理只读查询（A1 篇功能版图）。

6.3 想在 CI 里自动编目数据源，用哪种身份？

用 service-accounts create + service-accounts apikeys 签机器密钥（4.8），与个人 Key 隔离，可随时吊销；不要给 CI 用 admin 个人 Key。

6.4 runs get 一直 404？

见陷阱二：表格 ID 是 run_id，先 runs list -o json 拿 id 再查。

6.5 删除命令报 not found，要不要重试？

先 get/list 复核：大概率已删成功（陷阱一），重试会真的 not found。

七、参考链接

Marmot 0.11.1 常用 CLI 命令详解 - Quzuo