@ftirelo/triage-cli

Declarative Gmail filter management from the command line.

Triage lets you manage Gmail filters and labels declaratively: rules live in a version-controllable JSON format, and the triage CLI syncs them to Gmail with a dry-run-by-default, confirm, snapshot, apply safety flow. Instead of clicking through Gmail's settings, you describe the desired state of your inbox and let Triage compute and apply the diff — reversibly.

Install

Requires Node.js 20+.

npm install -g @ftirelo/triage-cli
triage --version

Quick start

triage auth login                       # browser sign-in handoff; caches a token
triage whoami                           # confirm which Gmail account you're using

triage import --from rules.json         # load rules from a file…
triage import --from-gmail              # …or reverse-import your existing filters
triage list                             # view stored rules

triage sync                             # DRY-RUN (default): print the plan, change nothing
triage sync --apply                     # confirm + snapshot + apply to Gmail

triage status                           # detect drift between Gmail and your rules
triage history --audit                  # review syncs, snapshots, and the audit log

triage snapshot --label "before cleanup"
triage rollback --apply                 # restore the most recent snapshot

Commands

| Command | What it does | | :---------------- | :--------------------------------------------------------------------- | | triage auth | login / status / logout — browser sign-in handoff | | triage whoami | Show the signed-in Gmail address | | triage import | Load rules from rules.json or reverse-import from Gmail | | triage list | List stored rules with query and actions; --json for raw output | | triage sync | Diff rules vs. Gmail; --apply to mutate, --yes for non-interactive | | triage status | Read-only drift report | | triage snapshot | Capture the current Gmail filter state as a restore point | | triage rollback | Preview/apply a snapshot restore (dry-run by default) | | triage history | Recent syncs and snapshots; --audit adds the audit log |

Rules format

Each rule is a Gmail search query plus one or more actions (archive, markRead, addLabel, removeLabel, star):

{
  "version": 1,
  "rules": [
    {
      "id": "github-notifications",
      "name": "GitHub notifications → label + archive",
      "query": "from:[email protected]",
      "actions": [{ "type": "addLabel", "label": "Dev/GitHub" }, { "type": "archive" }]
    }
  ]
}

Safety rails

• No destructive actions — there is no delete/trash/spam action; the schema rejects anything else. Triage never deletes mail.
• Dry-run is the default for sync and rollback; --apply is required to mutate, and prompts for confirmation unless --yes is passed.
• Automatic snapshots before every sync and rollback, so changes are reversible.

Documentation

Full documentation, the rules starter file, and the web dashboard live in the gmail-filters repository.

License

MIT