agy-powerline 1.2.0 → 1.3.0

package/README.zh-CN.md

@@ -1,12 +1,16 @@
 # agy-powerline
 
-[English](README.md) | **简体中文** | [日本語](README.ja.md)
+[English](README.md) | **简体中文** | [日本語](README.ja.md) | [Français](README.fr.md)
 
 [![CI](https://github.com/wassim-azi/agy-powerline/actions/workflows/ci.yml/badge.svg)](https://github.com/wassim-azi/agy-powerline/actions/workflows/ci.yml)
 [![Version](https://img.shields.io/npm/v/agy-powerline.svg)](https://www.npmjs.com/package/agy-powerline)
+[![Downloads](https://img.shields.io/npm/dt/agy-powerline.svg)](https://www.npmjs.com/package/agy-powerline)
 [![Node](https://img.shields.io/badge/node-%3E%3D20-informational.svg)](https://nodejs.org/)
+[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-informational.svg)](docs/install.md)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](#隐私与安全)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/wassim-azi/agy-powerline/badge)](https://scorecard.dev/viewer/?uri=github.com/wassim-azi/agy-powerline)
+[![Mentioned in Awesome Gemini CLI](https://img.shields.io/badge/mentioned%20in-awesome-fc60a8.svg?logo=awesomelists&logoColor=white)](https://github.com/Piebald-AI/awesome-gemini-cli)
 
 > 本文译自英文版 [README](README.md)，可能落后于英文版；如有出入，以英文版为准。详细文档（[`docs/`](docs/)）仅提供英文版。
 
@@ -30,6 +34,14 @@ agy                           # 启动 Antigravity
 
 `init` 在替换任何内容之前都会先询问，并会先备份 Antigravity 的 `settings.json`。运行 `init` 后需重启一次 `agy`。详情：[`init` 做了什么](docs/install.md)。
 
+也可以让 agy 帮你安装：把下面这段话粘贴到 `agy` 会话中。
+
+```text
+Install the agy-powerline statusline: run `npx agy-powerline init --yes`, then tell me to restart agy.
+```
+
+`--yes` 会跳过 agy 无法回答的确认提示，并在备份 `settings.json` 后替换已有的 `statusLine`。
+
 如果终端没有 Nerd Font，可以开启 ASCII 模式（在 `configure` 中按 `i`）。
 
 ## 自定义
@@ -52,12 +64,12 @@ agy                           # 启动 Antigravity
 
 ### 主题
 
-| 终端背景   | 主题                                                                                                                                   |
-| ---------- | -------------------------------------------------------------------------------------------------------------------------------------- |
-| 深色       | `dark-aurora`（默认）、`dark-ocean`、`dark-ember`、`dark-forest`、`dark-neon`、`dark-mono`、`dark-nocturne`、`dark-onyx`、`dark-metro` |
-| 浅色       | `light-paper`、`light-sky`、`light-sunset`、`light-cream`                                                                              |
-| 色盲友好   | `colorblind-dark`、`colorblind-light`                                                                                                  |
-| 自定义颜色 | `custom`（[方法](docs/configuration.md#custom-theme)）                                                                                 |
+| 终端背景   | 主题                                                                                                                                                     |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 深色       | `dark-aurora`（默认）、`dark-ocean`、`dark-ember`、`dark-forest`、`dark-neon`、`dark-mono`、`dark-nocturne`、`dark-onyx`、`dark-metro`、`dark-macchiato` |
+| 浅色       | `light-paper`、`light-sky`、`light-sunset`、`light-cream`                                                                                                |
+| 色盲友好   | `colorblind-dark`、`colorblind-light`                                                                                                                    |
+| 自定义颜色 | `custom`（[方法](docs/configuration.md#custom-theme)）                                                                                                   |
 
 用 `npx agy-powerline theme --gallery` 预览所有主题。
 
@@ -78,42 +90,47 @@ agy                           # 启动 Antigravity
 
 ## 组件
 
-| 组件                                                    | 显示内容                                                                             |
-| ------------------------------------------------------- | ------------------------------------------------------------------------------------ |
-| `model`                                                 | 当前使用的模型                                                                       |
-| `fiveHourBar`、`weeklyBar`                              | 以进度条显示 5h / 7d 剩余配额，带[进度标记](docs/configuration.md#quota-pace-marker) |
-| `fiveHourPct`、`weeklyPct`                              | 以百分比显示 5h / 7d 剩余配额                                                        |
-| `fiveHourReset`、`weeklyReset`                          | 距配额重置的时间，或重置时刻                                                         |
-| `quota`                                                 | 最接近用完的配额及其重置时间                                                         |
-| `thirdPartyFiveHour`、`thirdPartyWeekly`                | 第三方模型的配额                                                                     |
-| `argonWeekly`、`argonReset`                             | Gemini 4 Argon 独立的每周配额（Google AI Pro）及其重置时间                           |
-| `context`、`contextPct`、`contextTokens`                | 已用的上下文窗口：进度条、百分比或 token 数                                          |
-| `git`                                                   | 分支、未提交的更改以及领先/落后的提交数                                              |
-| `project`、`cwd`                                        | 项目文件夹、当前文件夹                                                               |
-| `agentState`、`plan`、`sandbox`、`artifacts`、`version` | 代理正在做什么、你的套餐、沙箱、产物、CLI 版本                                       |
-| `tasks`                                                 | 正在运行的子代理和后台任务                                                           |
-| `mode`                                                  | 审批模式（如 accept-edits）和 Vim 模式                                               |
-| `title`                                                 | 对话标题                                                                             |
-| `totalTokens`、`cacheHit`、`cacheRead`、`cacheCreate`   | 会话 token 数和提示缓存的使用情况                                                    |
-| `ram`                                                   | 本机已用内存                                                                         |
-| `customText`、`exec`                                    | 你自己的文本，或 [shell 命令](docs/configuration.md#shell-command-widget-exec)的输出 |
+| 组件                                                          | 显示内容                                                                                                 |
+| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `model`                                                       | 当前使用的模型                                                                                           |
+| `fiveHourBar`、`weeklyBar`                                    | 以进度条显示 5h / 7d 剩余配额，带[进度标记](docs/configuration.md#quota-pace-marker)                     |
+| `fiveHourPct`、`weeklyPct`                                    | 以百分比显示 5h / 7d 剩余配额                                                                            |
+| `fiveHourReset`、`weeklyReset`                                | 距配额重置的时间，或重置时刻                                                                             |
+| `quota`                                                       | 最接近用完的配额及其重置时间                                                                             |
+| `thirdPartyFiveHour`、`thirdPartyWeekly`                      | 第三方模型的配额                                                                                         |
+| `argonWeekly`、`argonReset`                                   | Gemini 4 Argon 独立的每周配额（Google AI Pro）及其重置时间                                               |
+| `context`、`contextPct`、`contextTokens`                      | 已用的上下文窗口：进度条、百分比或 token 数                                                              |
+| `git`                                                         | 分支、未提交的更改以及领先/落后的提交数                                                                  |
+| `gitChanges`, `gitFiles`, `gitSha`, `gitStash`, `gitWorktree` | Lines added and removed, staged/modified/untracked/conflicted files, commit ID, stashes, linked worktree |
+| `project`、`cwd`                                              | 项目文件夹、当前文件夹                                                                                   |
+| `agentState`、`plan`、`sandbox`、`artifacts`、`version`       | 代理正在做什么、你的套餐、沙箱、产物、CLI 版本                                                           |
+| `tasks`                                                       | 正在运行的子代理和后台任务                                                                               |
+| `mode`                                                        | 审批模式（如 accept-edits）和 Vim 模式                                                                   |
+| `title`                                                       | 对话标题                                                                                                 |
+| `totalTokens`、`cacheHit`、`cacheRead`、`cacheCreate`         | 会话 token 数和提示缓存的使用情况                                                                        |
+| `tokensToday`、`tokensWeek`                                   | 今天和过去 7 天的 token 用量（所有对话，Node 22.13+）                                                    |
+| `ram`                                                         | 本机已用内存                                                                                             |
+| `customText`、`exec`                                          | 你自己的文本，或 [shell 命令](docs/configuration.md#shell-command-widget-exec)的输出                     |
 
 没有内容可显示的组件会自动隐藏。组件可以更改颜色、去掉标签，或设置自己的告警阈值：见 [Configuration](docs/configuration.md)。
 
 ## 命令
 
-| 命令                                      | 作用                                               |
-| ----------------------------------------- | -------------------------------------------------- |
-| `npx agy-powerline init [--yes]`          | 安装或更新状态栏                                   |
-| `npx agy-powerline configure`             | 打开编辑器（别名 `config`）                        |
-| `npx agy-powerline preset <name>`         | 应用预设（`--list` 查看全部）                      |
-| `npx agy-powerline theme <name>`          | 切换主题（`--list`、`--gallery`）                  |
-| `npx agy-powerline layout <pills\|lines>` | 切换布局                                           |
-| `npx agy-powerline caps <style>`          | 切换胶囊形状：`round`、`angled`、`slanted`、`flat` |
-| `npx agy-powerline doctor`                | 检查安装并说明问题所在                             |
-| `npx agy-powerline report`                | 生成保护隐私的错误报告                             |
-| `npx agy-powerline uninstall [--delete]`  | 从 agy 中移除（`--delete` 会同时删除其文件）       |
-| `npx agy-powerline render --demo`         | 用示例数据打印状态栏                               |
+| 命令                                      | 作用                                                  |
+| ----------------------------------------- | ----------------------------------------------------- |
+| `npx agy-powerline init [--yes]`          | 安装或更新状态栏                                      |
+| `npx agy-powerline configure`             | 打开编辑器（别名 `config`）                           |
+| `npx agy-powerline preset <name>`         | 应用预设（`--list` 查看全部）                         |
+| `npx agy-powerline theme <name>`          | 切换主题（`--list`、`--gallery`）                     |
+| `npx agy-powerline gradient <name>`       | Color each row with a gradient (`--list`, `off`)      |
+| `npx agy-powerline layout <pills\|lines>` | 切换布局                                              |
+| `npx agy-powerline caps <style>`          | 切换胶囊形状：`round`、`angled`、`slanted`、`flat`    |
+| `npx agy-powerline export [file]`         | Save your config to a file, to back it up or share it |
+| `npx agy-powerline import <file>`         | Load a config, after showing what changes (`--merge`) |
+| `npx agy-powerline doctor`                | 检查安装并说明问题所在                                |
+| `npx agy-powerline report`                | 生成保护隐私的错误报告                                |
+| `npx agy-powerline uninstall [--delete]`  | 从 agy 中移除（`--delete` 会同时删除其文件）          |
+| `npx agy-powerline render --demo`         | 用示例数据打印状态栏                                  |
 
 任何命令加上 `--help` 即可查看其选项。
 
@@ -143,6 +160,31 @@ npx agy-powerline doctor       # 检查一切是否为最新
 
 欢迎贡献。请先阅读 [CONTRIBUTING.md](CONTRIBUTING.md)（环境搭建、架构、添加组件或主题）和 [Code of Conduct](CODE_OF_CONDUCT.md)。Pull request 请提交到 `develop` 分支。在 [GitHub issues](https://github.com/wassim-azi/agy-powerline/issues) 中报告错误，或在 [Discussions](https://github.com/wassim-azi/agy-powerline/discussions) 中分享想法和反馈。
 
+感谢所有贡献者：
+
+<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-disable -->
+<table>
+  <tbody>
+    <tr>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/yatharth2soni"><img src="https://avatars.githubusercontent.com/u/238868599?v=4&s=160" width="80" height="80" alt="Yatharth Soni"/><br /><sub><b>Yatharth Soni</b></sub></a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/dannyward630"><img src="https://avatars.githubusercontent.com/u/71604164?v=4&s=160" width="80" height="80" alt="Danny Ward"/><br /><sub><b>Danny Ward</b></sub></a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/yoreva-01"><img src="https://avatars.githubusercontent.com/u/195282707?v=4&s=160" width="80" height="80" alt="Yusuf Orçan"/><br /><sub><b>Yusuf Orçan</b></sub></a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/yuefdev"><img src="https://avatars.githubusercontent.com/u/120668197?v=4&s=160" width="80" height="80" alt="Yusuf Efe"/><br /><sub><b>Yusuf Efe</b></sub></a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/hiyouwhatsapp"><img src="https://avatars.githubusercontent.com/u/89997383?v=4&s=160" width="80" height="80" alt="hiyouwhatsapp"/><br /><sub><b>hiyouwhatsapp</b></sub></a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/dharamdan01"><img src="https://avatars.githubusercontent.com/u/188893946?v=4&s=160" width="80" height="80" alt="dharamdan01"/><br /><sub><b>dharamdan01</b></sub></a></td>
+    </tr>
+  </tbody>
+</table>
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+
+<!-- ALL-CONTRIBUTORS-LIST:END -->
+
+如果 agy-powerline 对你有用，点个 ⭐ 能帮助更多 agy 用户发现它。
+
 ## 许可证
 
 [MIT](LICENSE) © Wassim AZI

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agy-powerline",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Fast, configurable statusline for Google Antigravity CLI (agy): live Gemini, Claude/GPT and Argon quota pacing, git, and an interactive TUI configurator",
   "bin": {
     "agy-powerline": "src/index.js"
@@ -35,6 +35,7 @@
     "test:update": "node tests/update-snapshots.js",
     "test:coverage": "node --test --experimental-test-coverage tests/shared.js",
     "gallery": "node scripts/gallery/build.js",
+    "configurator": "node scripts/configurator/build.js",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "format": "prettier --write .",
@@ -71,6 +72,6 @@
     "@eslint/js": "10.0.1",
     "eslint": "10.12.0",
     "globals": "17.13.0",
-    "prettier": "3.9.9"
+    "prettier": "3.9.10"
   }
 }

package/src/cli/caps.js

@@ -1,3 +1,5 @@
+"use strict";
+
 const {
   saveConfig,
   setConfigDir,

package/src/cli/configure.js

@@ -1,3 +1,5 @@
+"use strict";
+
 const readline = require("readline");
 const { spawn } = require("child_process");
 const {
@@ -19,11 +21,10 @@ const {
   PRESETS,
   PRESET_ORDER,
   applyPreset,
-  resolveQuotaThresholds,
-  resolveContextThresholds,
 } = require("../lib/shared");
 const { resolveInstallDir } = require("../lib/paths");
 const { WIDGET_TAGS } = require("../lib/widget-style");
+const { editFields: getEditFields } = require("../lib/widget-options");
 const { loadEditableConfig } = require("./config-guard");
 const {
   parseColor,
@@ -48,7 +49,7 @@ const {
   glyphName,
 } = require("../lib/powerline");
 
-const REPO_URL = "https://github.com/wassim-azi/agy-powerline";
+const { REPO_URL } = require("./repo-url");
 
 const CSI = "\x1b[";
 const RESET = `${CSI}0m`;
@@ -749,151 +750,14 @@ function drawMain() {
   });
 }
 
-// Widgets that take each option, as the layouts read them.
-const QUOTA_WIDGETS = new Set([
-  "quota",
-  "fiveHourBar",
-  "fiveHourPct",
-  "weeklyBar",
-  "weeklyPct",
-  "thirdPartyFiveHour",
-  "thirdPartyWeekly",
-  "argonWeekly",
-]);
-const PACED_WIDGETS = new Set([
-  "fiveHourBar",
-  "weeklyBar",
-  "thirdPartyFiveHour",
-  "thirdPartyWeekly",
-  "argonWeekly",
-]);
-const CONTEXT_WIDGETS = new Set(["context", "contextPct", "contextTokens"]);
-const RESET_WIDGETS = new Set(["fiveHourReset", "weeklyReset", "argonReset"]);
-const COLOR_SLOTS = ["model", "context", "git", "weekly", "thirdParty", "fiveHour", "meta"];
 // Longest custom badge text; the badge is meant to be a word or two.
 const TEXT_MAX = 40;
 
-const onOff = (value) => (value ? "on" : "off");
-
-// The options of one widget: cycle fields step through values, number fields
-// step by 5 with the arrows, text fields take typing, and fixed ones only show
-// their value. undefined means "not set": the widget follows the global
-// setting or its default.
 function editFields(widget) {
-  const quota = QUOTA_WIDGETS.has(widget.id);
-  const context = CONTEXT_WIDGETS.has(widget.id);
-  const thresholds = quota
-    ? resolveQuotaThresholds({}, config)
-    : context
-      ? resolveContextThresholds({}, config)
-      : null;
-  const fields = [
-    {
-      key: "color",
-      label: "Color",
-      values: [undefined, ...COLOR_SLOTS],
-      show: (value) => (value === undefined ? "theme default" : colorName(value)),
-      help: "Draws this widget in another of the theme's colors. Caution and danger colors still take over when a quota or the context runs low.",
-    },
-    {
-      key: "raw",
-      label: "Label",
-      values: [undefined, false, true],
-      show: (value) =>
-        value === undefined
-          ? `default (${config.minimalist ? "hidden" : "shown"})`
-          : value
-            ? "hidden, value only"
-            : "shown",
-      help: "Shows or hides the icon and label before the value. Default follows minimalist mode (m).",
-    },
-  ];
-
-  if (widget.id === "model") {
-    fields.push({
-      key: "short",
-      label: "Short name",
-      values: [undefined, true],
-      show: (value) => onOff(value),
-      help: "3.8 Flash·High instead of Gemini 3.8 Flash (High).",
-    });
-  }
-  if (widget.id === "totalTokens") {
-    fields.push({
-      key: "split",
-      label: "Split",
-      values: [undefined, true],
-      show: (value) => onOff(value),
-      help: "Input and output tokens apart (123.1K↑ 355.0K↓) instead of one total.",
-    });
-  }
-  if (RESET_WIDGETS.has(widget.id)) {
-    fields.push({
-      key: "format",
-      label: "Format",
-      values: [undefined, "time", "both"],
-      show: (value) => value ?? "countdown",
-      help: "countdown (2hr 47m), time (6:33pm) or both (6:33pm (2hr 47m)).",
-    });
-  }
-  if (widget.id === "customText") {
-    fields.push({
-      key: "text",
-      label: "Text",
-      text: true,
-      show: (value) => value || "(empty: hidden)",
-      help: "The badge's text. Enter to type, Enter again to keep it, Esc to cancel.",
-    });
-  }
-  if (widget.id === "exec") {
-    fields.push({
-      key: "cmd",
-      label: "Command",
-      fixed: true,
-      show: (value) => value || "(none)",
-      help: `The command runs only in agy, from your install folder. Edit it in ${getConfigPath()}.`,
-    });
-  }
-  if (thresholds) {
-    const what = quota ? "left" : "used";
-    fields.push(
-      {
-        key: "warn",
-        label: "Caution at",
-        number: thresholds.warn,
-        show: (value) => (value === undefined ? `default (${thresholds.warn}%)` : `${value}%`),
-        help: `Turns to the caution color at this share ${what}.`,
-      },
-      {
-        key: "crit",
-        label: "Danger at",
-        number: thresholds.crit,
-        show: (value) => (value === undefined ? `default (${thresholds.crit}%)` : `${value}%`),
-        help: `Turns to the danger color at this share ${what}.`,
-      },
-      {
-        key: "blink",
-        label: "Blink",
-        values: [undefined, true, "warn", false],
-        show: (value) =>
-          value === undefined
-            ? `default (${thresholds.blink ? "on" : "off"})`
-            : { true: "at danger", warn: "at caution and danger", false: "off" }[String(value)],
-        help: "Makes the widget blink when it reaches the danger (or caution) level. ASCII mode never blinks.",
-      }
-    );
-  }
-  if (PACED_WIDGETS.has(widget.id)) {
-    fields.push({
-      key: "pace",
-      label: "Pace marker",
-      values: [undefined, false, true],
-      show: (value) =>
-        value === undefined ? `default (${onOff(config.pacing !== false)})` : onOff(value),
-      help: "Marks where usage would be if it were spread evenly over the window. Default follows r.",
-    });
-  }
-  return fields;
+  return getEditFields(widget, config, {
+    colorName: (value) => (value === undefined ? "theme default" : colorName(value)),
+    cmdHelp: `The command runs only in agy, from your install folder. Edit it in ${getConfigPath()}.`,
+  });
 }
 
 // A theme slot's color name, in that color.

package/src/cli/doctor.js

@@ -1,3 +1,5 @@
+"use strict";
+
 const fs = require("fs");
 const os = require("os");
 const path = require("path");
@@ -23,6 +25,7 @@ const {
 const { runStatuslineCommand } = require("../lib/run");
 const { detectColorDepth } = require("../lib/colors");
 const { readLog, getLogPath } = require("../lib/log");
+const { USAGE_PERIODS, usageAvailable } = require("../lib/usage");
 const { version } = require("../../package.json");
 
 const DIM = "\x1b[2m";
@@ -144,6 +147,15 @@ async function doctorCommand(options = {}) {
     console.log("  The bar shows the defaults until you fix the file or delete it.");
   }
 
+  // Not a failure: the widgets just hide.
+  if (configState.config.widgets.some((widget) => USAGE_PERIODS[widget.id]) && !usageAvailable()) {
+    console.log();
+    console.log(
+      `${YELLOW} usage widgets need Node 22.13 or newer${RESET} (this is ${process.version}).`
+    );
+    console.log("  tokensToday and tokensWeek stay hidden until Node is updated.");
+  }
+
   const breaking = cmdBreakingChars(installDir);
   if (breaking.length) {
     failed += 1;

package/src/cli/export.js

@@ -0,0 +1,82 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { readConfigFile, mergeConfig, setConfigDir } = require("../lib/shared");
+const { resolveInstallDir, writeFileAtomic, PRIVATE_FILE_MODE } = require("../lib/paths");
+const { printInvalidConfig } = require("./config-guard");
+const { version } = require("../../package.json");
+
+const DIM = "\x1b[2m";
+const GREEN = "\x1b[32m";
+const RED = "\x1b[31m";
+const YELLOW = "\x1b[33m";
+const RESET = "\x1b[0m";
+
+// The config as the bar reads it, with the release that wrote it first, so an
+// import can tell a file from a newer release.
+function exportDocument(config) {
+  return { agyPowerline: { version }, ...mergeConfig(config) };
+}
+
+function execCommandCount(config) {
+  return (config.widgets || []).filter(
+    (widget) => widget.id === "exec" && String(widget.cmd || "").trim()
+  ).length;
+}
+
+async function exportCommand(file, options = {}) {
+  const installDir = resolveInstallDir();
+  if (!installDir) {
+    return;
+  }
+
+  setConfigDir(installDir);
+  const { config, error } = readConfigFile();
+  if (error) {
+    // Exporting the defaults would look like a backup of the user's bar.
+    printInvalidConfig(error);
+    process.exitCode = 1;
+    return;
+  }
+
+  const body = JSON.stringify(exportDocument(config), null, 2) + "\n";
+
+  if (file) {
+    const target = path.resolve(String(file));
+    let existing = null;
+    try {
+      existing = fs.statSync(target);
+    } catch {
+      // Nothing there yet.
+    }
+    if (existing?.isDirectory()) {
+      console.error(`${RED}error${RESET} ${target} is a folder. Name a file to write.`);
+      process.exitCode = 1;
+      return;
+    }
+    if (existing && !options.force) {
+      console.error(`${RED}error${RESET} ${target} already exists. Pass --force to replace it.`);
+      process.exitCode = 1;
+      return;
+    }
+    // Owner-only, like the config itself: it can hold your commands.
+    writeFileAtomic(target, body, { mode: PRIVATE_FILE_MODE });
+    console.error(`${GREEN}✔${RESET} Config exported to ${DIM}${target}${RESET}`);
+  } else {
+    process.stdout.write(body);
+  }
+
+  // Notes go to stderr, so `export > file` keeps the JSON clean.
+  const commands = execCommandCount(config);
+  if (commands) {
+    console.error(
+      `${YELLOW}note${RESET} The export holds ${commands} exec widget command${commands === 1 ? "" : "s"}; check ${commands === 1 ? "it" : "them"} before sharing the file.`
+    );
+  }
+}
+
+module.exports = {
+  exportCommand,
+  exportDocument,
+};

package/src/cli/gradient.js

@@ -0,0 +1,121 @@
+"use strict";
+
+const {
+  saveConfig,
+  setConfigDir,
+  getConfigPath,
+  renderStatusline,
+  sampleData,
+  resolveColorDepth,
+} = require("../lib/shared");
+const { GRADIENTS, GRADIENT_ORDER, normalizeGradient, gradientStops } = require("../lib/themes");
+const { bg, gradientColors, setActiveDepth, getActiveDepth } = require("../lib/colors");
+const { resolveInstallDir } = require("../lib/paths");
+const { loadEditableConfig } = require("./config-guard");
+
+const DIM = "\x1b[2m";
+const BOLD = "\x1b[1m";
+const GREEN = "\x1b[32m";
+const RED = "\x1b[31m";
+const CYAN = "\x1b[36m";
+const RESET = "\x1b[0m";
+
+const STRIP_WIDTH = 24;
+
+// A row of colored cells showing the gradient; empty without color.
+function gradientStrip(value, config) {
+  const stops = gradientStops(value);
+  if (!stops) {
+    return "";
+  }
+  const previous = getActiveDepth();
+  setActiveDepth(resolveColorDepth({ configColor: config.color, env: process.env }));
+  try {
+    if (getActiveDepth() === "none") {
+      return "";
+    }
+    const cells = gradientColors(stops, STRIP_WIDTH).map((color) => `${bg(color)} `);
+    return `${cells.join("")}${RESET}`;
+  } finally {
+    setActiveDepth(previous);
+  }
+}
+
+function listGradients(config) {
+  const current = config.gradient || "off";
+
+  console.log();
+  console.log(`${BOLD} agy-powerline gradients${RESET}`);
+  console.log(`  current  ${CYAN}${current}${RESET} ${gradientStrip(config.gradient, config)}`);
+  console.log(`  config   ${DIM}${getConfigPath()}${RESET}`);
+  console.log();
+
+  const maxIdLen = Math.max(...GRADIENT_ORDER.map((id) => id.length), "off".length);
+
+  for (const id of [...GRADIENT_ORDER, "off"]) {
+    const isCurrent = id === current;
+    const marker = isCurrent ? `${GREEN}*${RESET}` : " ";
+    const idFormatted = isCurrent
+      ? `${BOLD}${CYAN}${id.padEnd(maxIdLen)}${RESET}`
+      : id.padEnd(maxIdLen);
+    const preview = id === "off" ? `${DIM}theme colors only${RESET}` : gradientStrip(id, config);
+    console.log(`  ${marker} ${idFormatted}  ${preview}`);
+  }
+
+  console.log();
+  console.log(` Run ${CYAN}npx agy-powerline gradient <name>${RESET} to color each row.`);
+  console.log(` Your own colors: ${CYAN}npx agy-powerline gradient "#ff5f6d-#ffc371"${RESET}`);
+  console.log();
+}
+
+async function gradientCommand(name, options = {}) {
+  const installDir = resolveInstallDir();
+  if (!installDir) {
+    return;
+  }
+
+  setConfigDir(installDir);
+  const config = loadEditableConfig();
+  if (!config) {
+    return;
+  }
+
+  if (!name || options.list) {
+    listGradients(config);
+    return;
+  }
+
+  const raw = String(name).trim();
+  const off = raw.toLowerCase() === "off";
+  const value = off ? null : normalizeGradient(raw);
+
+  if (!off && !value) {
+    console.error(`${RED}error${RESET} Unknown gradient "${raw}".`);
+    console.error(` Available gradients: ${GRADIENT_ORDER.join(", ")}, off`);
+    console.error(" Or 2 to 6 hex colors joined by dashes, e.g. #ff5f6d-#ffc371");
+    process.exitCode = 1;
+    return;
+  }
+
+  if (off) {
+    delete config.gradient;
+  } else {
+    config.gradient = value;
+  }
+  saveConfig(config);
+
+  const title = off ? "off" : GRADIENTS[value]?.name || value;
+
+  console.log();
+  console.log(`${GREEN}✔${RESET} Gradient set to ${BOLD}${title}${RESET}`);
+  console.log(`  config  ${DIM}${getConfigPath()}${RESET}`);
+  console.log();
+  console.log(" Preview:");
+  console.log(renderStatusline(sampleData(), config));
+  console.log();
+}
+
+module.exports = {
+  gradientCommand,
+  gradientStrip,
+};