tags

Tags are the key=value attribution labels the SDK sends with spend and the CLI sends with budget check, confirm, and record. tags browses the account-wide registry of keys and values that successful ingest has created, and retires keys you no longer need. Discovery is account-scoped even when you pass a project — the project only routes the request.

Sending and enforcing tags works on every tier. Only discovery needs Team; on a lower tier the API answers with an upgrade response, the CLI prints Tag analytics need Team. to stderr, and exits 1.

tags list

List the account's active keys.

$ solwyn --project proj_0123456789abcdef01234567 tags list
Key  Values  First seen                 Last seen                  Similar
env  1       2026-09-05T12:00:00+00:00  2026-09-05T12:00:00+00:00   Env
Account tag keys: 1/100.

Keys are verbatim: case and whitespace are preserved and never merged. The Similar column lists other active keys that collide once trimmed and lower-cased — Env beside env, for instance — as a lint signal, not a merge. Each account holds up to 100 active keys and 1000 values per key; the usage line on stderr shows where you stand.

tags values

Read one page of values for a single key.

solwyn --project <project_id> tags values <key> [--prefix <p>] [--limit 1-100] [--cursor <c>] [--all]

$ solwyn --project proj_0123456789abcdef01234567 tags values env
Value  First seen                 Last seen
prod   2026-09-05T12:00:00+00:00  2026-09-05T12:00:00+00:00

Keys containing /, ?, #, or spaces work — the key travels as a query parameter. A cursor from a different key or prefix is refused with a usage error and the untrusted cursor is never echoed back. When more values remain, stderr prints the next cursor.

With --all, key and prefix persist on every page. Repeated cursors, inconsistent continuation, malformed responses or a later-page failure exit nonzero without partial success stdout. Exhausted JSON has next_cursor=null, has_more=false.

tags retire

Retire a key, keeping its historical values. The CLI displays account-wide slot and discovery effects on stderr and requires confirmation or --yes. Without a TTY and without --yes, it exits 2 before HTTP. Decline, EOF or Ctrl-C submits no retirement.

$ solwyn tags retire env --yes
Key  Retired
env  yes
Later successful ingest may reactivate this key if account capacity permits.

Retirement removes the key from discovery and frees one of the account's active-key slots. It is not destructive: historical values are retained, retiring an already-retired key succeeds, and a later ingest that carries the key may reactivate it if capacity permits. There is no unretire command because none is needed. A project key exits 3 with jwt_required before any request.

Related

• costs — filter with --tag key=value or group by tag:<key>
• budget — attach tags to a check, confirm, or record with --tag or SOLWYN_TAGS
• Agent runs — how the SDK attaches tags to runs and calls