MokoNtfy CLI — groups, roles & protected topics

Details
Category: Reference
  • Applicable Software: MokoNtfy

MokoNtfy adds three server-side CLI commands for the access-control system introduced in 01.06.00, alongside the existing ntfy user and ntfy access. They are the command-line equivalent of the Site Administration pages.

Two of them run against the auth database directly (ntfy group and ntfy role) — they must run on the server host with access to server.yml / auth-file, and take no token. One runs against the live server over HTTP (ntfy protect) and needs --server plus an admin/owner --token.

ntfy group

Manage user groups and group topic access. A grant made to a group applies to every member. Group access is additive-only: a user's effective permission is the union of their groups' grants, so a deny/none permission is rejected — to subtract, add a per-user deny with ntfy access USERNAME TOPIC deny, which always wins.

ntfy group list                       # Show all groups, members and grants
ntfy group add GROUP                  # Create an empty group
ntfy group remove GROUP               # Delete a group (and its members/grants)

ntfy group member add GROUP USERNAME    # Add a user to a group (idempotent)
ntfy group member remove GROUP USERNAME # Remove a user from a group

ntfy group access GROUP TOPIC PERMISSION  # Grant topic access
ntfy group access reset GROUP [TOPIC]     # Remove one grant, or all of the group's grants

PERMISSION is one of read-write (alias rw), read-only (aliases read, ro), or write-only (aliases write, wo). TOPIC may include wildcards, e.g. "mytopic*". Aliases: add=a, remove=del/rm, list=l, access reset=r.

Examples

ntfy group add ops                    # Create group "ops"
ntfy group member add ops phil        # Add user phil to ops
ntfy group access ops alerts rw       # Grant ops read-write on "alerts"
ntfy group access ops "up*" write     # Grant ops write-only on "up..."
ntfy group access reset ops alerts    # Remove ops' grant for "alerts"
ntfy group access reset ops           # Remove all of ops' grants
ntfy group del ops                    # Delete ops

ntfy protect

Manage the protected-topics registry. A protected topic's ACL must be explicit — it is no longer reachable via the fall-through Everyone grant or the server default access (owners, admins and the reservation owner still retain access). This registry lives in the server's message-cache settings store, so unlike the other commands ntfy protect talks to the running server over its admin HTTP API (/v1/topics/protected). It therefore requires:

  • --server / -s — the ntfy server base URL (env NTFY_SERVER; default http://localhost:2586).
  • --token / -t — an admin/owner access token (env NTFY_TOKEN; create one with ntfy token add).
ntfy protect --token=TOKEN list                    # List protected topics
ntfy protect --token=TOKEN add TOPIC [--note=...]  # Mark a topic/pattern protected
ntfy protect --token=TOKEN remove TOPIC            # Unmark it

--note / -n records an optional reason with an added topic. Aliases: add=a/mark, remove=del/rm/unmark, list=l. Marking a topic protected removes its exact Everyone grant; a broader matching wildcard is left in place with a warning. Unprotecting does not re-grant Everyone access — reopen a topic deliberately with ntfy access.

Examples

ntfy protect --token=tk_... list
ntfy protect --token=tk_... add secret
ntfy protect --token=tk_... add "internal*" --note "staff only"
ntfy protect --token=tk_... remove secret

ntfy role

Manage RBAC roles — named bundles of capabilities (system-wide or topic-scoped) assignable to users or groups. Roles sit beside the coarse owner/admin/user role: admin and owner bypass every capability check, so roles gate delegated, non-admin access only. Role management is owner-only.

ntfy role list                                  # Show all roles, capabilities and assignments
ntfy role add ROLE                              # Create an empty role
ntfy role remove ROLE                           # Delete a role (caps + assignments)

ntfy role capability add ROLE CAPABILITY [SCOPE]    # Grant a capability (empty SCOPE = system-wide)
ntfy role capability remove ROLE CAPABILITY [SCOPE] # Remove a (capability, scope) grant

ntfy role assign ROLE (USERNAME|@g:GROUP)       # Assign to a user or a group
ntfy role unassign ROLE (USERNAME|@g:GROUP)     # Remove an assignment

A principal is either a username or a group in the @g:<group> form. A SCOPE is a topic name or * pattern (topic-scoped capabilities only); an empty scope is system-wide. Aliases: add=a, remove=del/rm, list=l, capability=cap.

Known capabilities: users.manage, acl.manage, groups.manage, branding.manage, tours.manage, approvals.manage, server.view, topics.acl.view, topics.protect.manage, topic.acl.manage, topic.protect.manage, topic.acl.view.

Examples

ntfy role add acl-delegate                                   # Create a role
ntfy role capability add acl-delegate topic.acl.manage "team-*"  # Topic-scoped capability
ntfy role capability add auditor topics.acl.view             # System-wide capability
ntfy role assign acl-delegate phil                           # Assign to user phil
ntfy role assign acl-delegate @g:ops                         # Assign to group ops
ntfy role unassign acl-delegate phil
ntfy role del acl-delegate

Where each command runs

  • ntfy group, ntfy role — auth-database-direct. Run on the server host; require auth-file in server.yml; no token.
  • ntfy protect — admin HTTP API. Can run anywhere that can reach the server; requires --server and an admin/owner --token.
Hits: 5