tomevault-io OpenFGA CLI Skill
You help the user query and debug their OpenFGA authorization model using the fga CLI.
Connection setup
Always use these flags:
--api-url http://localhost:9080
--api-token Azerty123_
Store ID: Do NOT hardcode a store ID. Resolve it dynamically by running:
fga store list --api-url http://localhost:9080 --api-token Azerty123_ | jq -r '.stores[] | select(.name == "fred") | .id'
Use the returned ID as the --store-id value for all subsequent commands.
Store the three flags in a variable for convenience:
STORE_ID=$(fga store list --api-url http://localhost:9080 --api-token Azerty123_ | jq -r '.stores[] | select(.name == "fred") | .id')
FGA_FLAGS="--api-url http://localhost:9080 --api-token Azerty123_ --store-id $STORE_ID"
Schema reference
Read the authorization schema at fred-core/fred_core/security/rebac/schema.fga to understand the types, relations, and permission rules before answering.
Available commands
1. Read tuples
List stored relationship tuples, optionally filtered.
# All tuples
fga tuple read $FGA_FLAGS
# Filter by object
fga tuple read $FGA_FLAGS --object <type>:<id>
# Filter by object + relation
fga tuple read $FGA_FLAGS --object <type>:<id> --relation <relation>
# Filter by user
fga tuple read $FGA_FLAGS --user <type>:<id>
2. Check a permission
Check if a user has a specific relation on an object (returns allowed: true/false).
fga query check $FGA_FLAGS <user_type>:<user_id> <relation> <object_type>:<object_id>
3. List objects a user can access
List all objects of a given type that a user has a relation on.
fga query list-objects $FGA_FLAGS <user_type>:<user_id> <relation> <object_type>
4. List users who have access to an object
fga query list-users $FGA_FLAGS <object_type>:<object_id> <relation> <user_type>
5. Expand a relation (userset tree)
Show the full resolution tree for a relation on an object.
fga query expand $FGA_FLAGS <relation> <object_type>:<object_id>
Handling $ARGUMENTS
Parse the user's intent from $ARGUMENTS. Examples:
/fga read tuples for tag:abc→fga tuple read $FGA_FLAGS --object tag:abc/fga can user:xyz read tag:abc?→fga query check $FGA_FLAGS user:xyz read tag:abc/fga why can user:xyz read tag:abc?→ Runcheck, thenexpand, then trace the tuple chain to explain the full resolution path/fga list objects user:xyz can read of type tag→fga query list-objects $FGA_FLAGS user:xyz read tag/fga who can read tag:abc?→fga query list-users $FGA_FLAGS tag:abc read user
Explaining a permission ("why" queries)
When the user asks why a user has a permission, follow this process:
- Check the permission exists:
fga query check ... - Expand the relation on the object:
fga query expand ... - Read tuples on the object to find the direct relationships:
fga tuple read ... --object <object> - Trace indirect paths: if the relation comes through a team, parent, or other intermediary, read tuples on those intermediary objects too
- Read the schema to explain which rule in the model grants the access
- Summarize the full chain in a clear, human-readable format showing each hop
Example output format:
user:alice → member of → team:engineering → owner of → tag:docs → read (via "member from owner" rule)
Notes
- Types in the schema:
user,organization,team,agent,tag,document,resource - Common relations:
owner,editor,viewer,member,manager,admin,parent - Common permissions:
read,update,delete,share,process
Converted and distributed by TomeVault — claim your Tome and manage your conversions.