gem-hunter

A cross-platform CLI to interact with an OpenFGA server

• About OpenFGA
• Resources
• Installation
• Building from Source
• Usage
  • Configuration
  • Custom Headers
  • Commands
    • Stores
      • List All Stores
      • Create a Store
      • Import a Store
      • Export a Store
      • Get a Store
      • Delete a Store
    • Authorization Models
      • Read Authorization Models
      • Write Authorization Model
      • Read a Single Authorization Model
      • Read the Latest Authorization Model
      • Validate an Authorization Model
      • Run Tests on an Authorization Model
      • Transform an Authorization Model
    • Relationship Tuples
      • Read Relationship Tuple Changes (Watch)
      • Read Relationship Tuples
      • Write Relationship Tuples
      • Delete Relationship Tuples
    • Relationship Queries
      • Check
      • Expand
      • List Objects
      • List Relations
      • List Users
    • Mapping
      • Validate a Mapping File
      • Run Embedded Tests
      • Scaffold a Mapping File
      • Evaluate Against JSON Input
      • Sync to Store
• Contributing
• License

OpenFGA is an open source Fine-Grained Authorization solution inspired by Google's Zanzibar paper. It was created by the FGA team at Auth0/Okta based on Auth0 Fine-Grained Authorization (FGA), available under a permissive license (Apache-2) and welcomes community contributions.

OpenFGA is designed to make it easy for application builders to model their permission layer, and to add and integrate fine-grained authorization into their applications. OpenFGA’s design is optimized for reliability and low latency at a high scale.

• OpenFGA Documentation
• OpenFGA API Documentation
• Zanzibar Academy
• Google's Zanzibar Paper (2019)

brew install openfga/tap/fga

Download the .deb, .rpm or .apk packages from the releases page.

Debian:

sudo apt install ./fga_<version>_linux_<arch>.deb

Fedora:

sudo dnf install ./fga_<version>_linux_<arch>.rpm

Alpine Linux:

sudo apk add --allow-untrusted ./fga_<version>_linux_<arch>.apk

via Scoop

scoop install openfga

docker pull openfga/cli; docker run -it openfga/cli

The Docker image is multi-platform and includes the system CA certificates needed for endpoints that use publicly trusted certificate authorities. Private or internal CAs still need to be provided by the user.

go install github.com/openfga/cli/cmd/fga@latest

Download the pre-compiled binaries from the releases page.

Make sure you have Go 1.25 or later installed. See the Go downloads page.

1. Clone the repo to a local directory, and navigate to that directory:

   git clone https://github.com/openfga/cli.git && cd cli

2. Then use the build command:

   go build -o ./dist/fga ./cmd/fga/main.go

   or if you have make installed, just run:

   make build

3. Run the OpenFGA CLI with:

   ./dist/fga

For any command that interacts with an OpenFGA server, these configuration values can be passed (where applicable)

If you are authenticating with a shared secret, you should specify the API Token value. If you are authenticating using OAuth, you should specify the Client ID, Client Secret, API Audience and Token Issuer. For example:

# Note: This example is for Auth0 FGA
api-url: https://api.us1.fga.dev
client-id: 4Zb..UYjaHreLKOJuU8
client-secret: J3...2pBwiauD
api-audience: https://api.us1.fga.dev/
api-token-issuer: auth.fga.dev
store-id: 01H0H015178Y2V4CX10C2KGHF4

You can add custom HTTP headers to all requests sent to the API using the --custom-headers flag. Headers are specified in <name>: <value> format, and the flag can be repeated to add multiple headers.

--custom-headers "Header-Name: header-value"

fga store list --custom-headers "X-Custom-Header: value1" --custom-headers "X-Request-ID: abc123"

Custom headers can also be configured via the CLI environment variable or the configuration file:

Example ~/.fga.yaml:

api-url: https://api.fga.example
store-id: 01H0H015178Y2V4CX10C2KGHF4
custom-headers:
  - "X-Custom-Header: value1"
  - "X-Request-ID: abc123"

fga store create

• --name: Name of the store to be created. If the model parameter is specified, the model file name will be used as the default store name.
• --model: File with the authorization model. Can be in JSON, OpenFGA format, or fga.mod file (optional).
• --format : Authorization model input format. Can be "fga", "json", or "modular" (optional, defaults to the model file extension if present).

fga store create --name "FGA Demo Store"

{
    "id": "01H0H015178Y2V4CX10C2KGHF4",
    "name": "FGA Demo Store",
    "created_at": "2023-05-19T16:10:07.637585677Z",
    "updated_at": "2023-05-19T16:10:07.637585677Z"
}

fga store create --model Model.fga

{
  "store": {
    "id":"01H6H9CNQRP2TVCFR7899XGNY8",
    "name":"Model",
    "created_at":"2023-07-29T16:58:28.984402Z",
    "updated_at":"2023-07-29T16:58:28.984402Z"
  },
  "model": {
    "authorization_model_id":"01H6H9CNQV36Y9WS1RJGRN8D06"
  }
}

To automatically set the created store id as an environment variable that will then be used by the CLI, you can use the following command:

export FGA_STORE_ID=$(fga store create --model model.fga | jq -r .store.id)

fga store import

• --file: File containing the store. See Store File Format for detailed documentation.
• --store-id: Specifies the store id to import into
• --max-tuples-per-write: Max tuples to send in a single write (optional, default=1)
• --max-parallel-requests: Max requests to send in parallel (optional, default=4)
• --allow-external-files: Allow model_file, tuple_file and tuple_files references in the store file to resolve outside the store file's directory (optional, default=false). Only enable this for store files you trust.

fga store import --file model.fga.yaml

{}

fga store export

• --store-id: Specifies the store to export
• --output-file: The file to output the store to (optional, writes to the terminal if omitted)
• --model-id: Specifies the model to export (optional, exports the latest model if omitted)
• --max-tuples: Specifies the max number of tuples to include in the output (optional, defaults to 100)

fga store export --store-id=01H0H015178Y2V4CX10C2KGHF4

name: Test
model: |+
  model
    schema 1.1

  type user

  type group
    relations
      define member: [user]
      define moderator: [user]

tuples:
  - user: user:1
    relation: member
    object: group:admins
  - user: user:1
    relation: member
    object: group:employees
  - user: user:2
    relation: member
    object: group:employees
  - user: user:1
    relation: moderator
    object: group:employees
tests:
  - name: Tests
    check:
      - user: user:1
        object: group:admins
        assertions:
          member: true
      - user: user:2
        object: group:admins
        assertions:
          member: false
      - user: user:1
        object: group:employees
        assertions:
          member: true
          moderator: true
      - user: user:2
        object: group:employees
        assertions:
          member: true
          moderator: false
      # checks can also be defined for multiple users sharing the same expectation
      - object: group:employees
        users:
          - user:1
          - user:2
        assertions:
          member: true

      # checks can also target multiple objects with the same expectation
      - objects:
          - group:admins
          - group:employees
        user: user:1
        assertions:
          member: true

If using output-file, the response will be written to the specified file on disk. If the desired file already exists, you will be prompted to overwrite the file.

fga store list

• --max-pages: Max number of pages to retrieve (default: 20)
• --name: Filter stores by exact name (substrings and regexes are not supported)

fga store list

fga store list --name="FGA Demo Store"

{
  "stores": [{
    "id": "..",
    "name": "..",
    "created_at": "",
    "updated_at": "",
    "deleted_at": ""
  }, { .. }]
}

fga store get

• --store-id: Specifies the store id to get

fga store get --store-id=01H0H015178Y2V4CX10C2KGHF4

{
    "id": "01H0H015178Y2V4CX10C2KGHF4",
    "name": "FGA Demo Store",
    "created_at": "2023-05-19T16:10:07.637585677Z",
    "updated_at": "2023-05-19T16:10:07.637585677Z"
}

fga store delete

• --store-id: Specifies the store id to delete

fga store delete --store-id=01H0H015178Y2V4CX10C2KGHF4

{}

• model

List all authorization models for a store, in descending order by creation date. The first model in the list is the latest one.

fga model list

• --store-id: Specifies the store id
• --max-pages: Max number of pages to retrieve (default: 20)
• --field: Fields to display. Choices are: id, created_at and model. Default are id, created_at.

fga model list --store-id=01H0H015178Y2V4CX10C2KGHF4

{
  "authorization_models": [
    {
      "id":"01H6H9XH1G5Q6DK6PFMGDZNH9S",
      "created_at":"2023-07-29T17:07:41Z"
    },
    {
      "id":"01H6H9PPR6C3P45R75X55ZFP46",
      "created_at":"2023-07-29T17:03:57Z"
    }
  ]
}

fga model write

• --store-id: Specifies the store id
• --file: File containing the authorization model.
• --format: Authorization model input format. Can be "fga", "json", or "modular". Defaults to the file extension if provided (optional)

• fga model write --store-id=01H0H015178Y2V4CX10C2KGHF4 --file=model.fga
• fga model write --store-id=01H0H015178Y2V4CX10C2KGHF4 --file=fga.mod
• fga model write --store-id=01H0H015178Y2V4CX10C2KGHF4 '{"type_definitions": [ { "type": "user" }, { "type": "document", "relations": { "can_view": { "this": {} } }, "metadata": { "relations": { "can_view": { "directly_related_user_types": [ { "type": "user" } ] }}}} ], "schema_version": "1.1"}' --format json

{
  "authorization_model_id":"01GXSA8YR785C4FYS3C0RTG7B1"
}

fga model get

• --store-id: Specifies the store id
• --model-id: Specifies the model id
• --format: Authorization model output format. Can be "fga" or "json" (default fga).
• --field: Fields to display, choices are: id, created_at, size and model. Default is model.

fga model get --store-id=01H0H015178Y2V4CX10C2KGHF4 --model-id=01GXSA8YR785C4FYS3C0RTG7B1 --field size --field model --field id --field created_at

# Model ID: 01GXSA8YR785C4FYS3C0RTG7B1
# Created At: 2023-04-11 23:26:34.759 +0000 UTC
# Size: 20.05 KB
model
  schema 1.1

type user

type document
  relations
    define can_view: [user]

In json format, the fields appear intermixed with the model.

fga model get --store-id=01H0H015178Y2V4CX10C2KGHF4 --model-id=01GXSA8YR785C4FYS3C0RTG7B1 --field size --field model --field id --field created_at --format=json

{
  "id":"01GXSA8YR785C4FYS3C0RTG7B1",
  "created_at":"2023-04-11T23:26:34.759Z",
  "size_kb":20.05,
  "schema_version":"1.1",
  "type_definitions": [...]
}

If model-id is not specified when using the get command, the latest authorization model will be returned.

fga model get

• --store-id: Specifies the store id

fga model get --store-id=01H0H015178Y2V4CX10C2KGHF4

model
  schema 1.1

type user

type document
  relations
    define can_view: [user]

fga model validate

• --file: File containing the authorization model.
• --format: Authorization model input format. Can be "fga", "json", or "modular". Defaults to the file extension if provided (optional)

fga model validate --file model.json

When the input parses successfully, the JSON response includes size_kb, the protobuf-serialized size of the model in KB. If the input cannot be parsed, the command exits with an error and does not emit a JSON response.

• Valid model with an ID

{"id":"01GPGWB8R33HWXS3KK6YG4ETGH","created_at":"2023-01-11T16:59:22Z","is_valid":true,"size_kb":0.05}

• Valid model without an ID

{"is_valid":true,"size_kb":0.05}

• Invalid model with an ID

{"id":"01GPGTVEH5NYTQ19RYFQKE0Q4Z","created_at":"2023-01-11T16:33:15Z","is_valid":false,"error":"invalid schema version","size_kb":0.05}

• Invalid model without an ID

{"is_valid":false,"error":"the relation type 'employee' on 'member' in object type 'group' is not valid","size_kb":0.05}

Given a model, and a set of tests (tuples, check and list objects requests, and expected results) report back on any tests that do not return the same results as expected.

fga model test

• --tests: Name of the tests file, or a glob pattern to multiple files (for example "tests/*.fga.yaml", or "**/*.fga.yaml"). Each file must be in yaml format. See Store File Format for detailed documentation.
• --verbose: Outputs the results in JSON
• --max-types-per-authorization-model: Max allowed number of type definitions per authorization model (default: 100). Increase this when testing models with more than 100 type definitions.
• --allow-external-files: Allow model_file, tuple_file and tuple_files references in the test file to resolve outside the test file's directory (optional, default=false). Only enable this for test files you trust.

If a model is provided, the test will run in a built-in OpenFGA instance (you do not need a separate server). Otherwise, the test will be run against the configured store of your OpenFGA instance. When running against a remote instance, the tuples will be sent as contextual tuples, and will have to abide by the OpenFGA server limits (20 contextual tuples per request).

The tests file should be in yaml and have the following format:

---
name: Store Name # store name, optional
# model_file: ./model.fga # a global model that would apply to all tests, optional
# model can be used instead of model_file, optional
model: |
  model
    schema 1.1
  type user
  type folder
    relations
      define owner: [user]
      define parent: [folder]
      define can_view: owner or can_view from parent
      define can_write: owner or can_write from parent
      define can_share: owner

# You can use `tuples`, `tuple_file`, and `tuple_files` together or individually to provide global tuples for all tests.
# Example using a single tuple file:
# tuple_file: ./tuples.yaml
# Example using multiple tuple files:
# tuple_files:
#   - ./model_tuples_2.yaml
#   - ./model_tuples_3.yaml
tuples: # global tuples that would apply to all tests, optional
  - user: folder:1
    relation: parent
    object: folder:2
tests: # required
  - name: test-1
    description: testing that the model works # optional
    # tuple_file: ./tuples.json # tuples that would apply per test
    tuples:
      - user: user:anne
        relation: owner
        object: folder:1
    check: # a set of checks to run
      - user: user:anne
        object: folder:1
        assertions:
          # a set of expected results for each relation
          can_view: true
          can_write: true
          can_share: false
      # checks can group multiple users that share the same expected results
      - object: folder:2
        users:
          - user:beth
          - user:carl
        assertions:
          can_view: false
      # checks can group multiple objects that share the same expected results
      - objects:
          - folder:1
          - folder:2
        user: user:beth
        assertions:
          can_write: false
      # either "user" or "users" may be provided, but not both
      # either "object" or "objects" may be provided, but not both
    list_objects: # a set of list objects to run
      - user: user:anne
        type: folder
        assertions:
          # a set of expected results for each relation
          can_view:
            - folder:1
            - folder:2
          can_write:
            - folder:1
            - folder:2
  - name: test-2
    description: another test
    tuples:
      - user: user:anne
        relation: owner
        object: folder:1
    check:
      - user: user:anne
        object: folder:1
        assertions:
          # a set of expected results for each relation
          can_view: true
    list_objects:
      - user: user:anne
        type: folder
        assertions:
          # a set of expected results for each relation
          can_view:
            - folder:1
            - folder:2

fga model test --tests "tests/*.fga.yaml"

For more examples of .fga.yaml files, check our Store File Format documentation and the sample-stores repository.

(FAILING) test-1: Checks (2/3 passing) | ListObjects (2/2 passing)
ⅹ Check(user=user:anne,relation=can_share,object=folder:1): expected=false, got=true
---
# Test Summary #
Tests 1/2 passing
Checks 3/4 passing
ListObjects 3/3 passing

The transform command lets you convert between different authorization model formats (.fga, .json, .mod).

fga model transform

• --file: File containing the authorization model
• --input-format: Authorization model input format. Can be "fga", "json", or "modular". Defaults to the file extension if provided (optional)
• --output-format: Authorization model output format. Can be "fga" or "json". If not specified, it will default to fga if the input format is json and to json otherwise (optional)

fga model transform --file model.json

model
  schema 1.1

type user

type document
  relations
    define can_view: [user]

• tuple

fga tuple write --store-id=

• <user>: User
• <relation>: Relation
• <object>: Object
• --condition-name: Condition name (optional)
• --condition-context: Condition context (optional)
• --condition-expression: Dynamic condition CEL expression (optional, mutually exclusive with --condition-name/--condition-context)
• --condition-parameters: Dynamic condition parameter types, as a JSON object with at least one parameter (requires --condition-expression)
• --store-id: Specifies the store id
• --model-id: Specifies the model id to target (optional)
• --file: Specifies the file name, json, jsonl, yaml and csv files are supported
• --max-tuples-per-write: Max tuples to send in a single write (optional, default=1, or 40 if --max-rps is set and this flag is omitted)
• --max-parallel-requests: Max requests to send in parallel (optional, default=4, or max-rps/5 if --max-rps is set and this flag is omitted)
• --hide-imported-tuples: When importing from a file, do not output successfully imported tuples in the command output (optional, default=false)
• --max-rps: Max requests per second. When set, the CLI will ramp up requests from 1 RPS to the set value. If --rampup-period-in-sec is omitted it defaults to max-rps*2.
• --rampup-period-in-sec: Time in seconds to wait between each batch of tuples when ramping up. Only used if --max-rps is set.
• --on-duplicate: Behavior when a tuple to be written already exists. Options are:
  • ignore: Skip the tuple and do not return an error. Default when importing via a file.
  • error: Return an error for the tuple. Default when writing a single tuple via arguments.
• All integer parameters must be greater than zero when provided.

• fga tuple write --store-id=01H0H015178Y2V4CX10C2KGHF4 user:anne can_view document:roadmap
• fga tuple write --store-id=01H0H015178Y2V4CX10C2KGHF4 user:anne can_view document:roadmap --condition-name inOffice --condition-context '{"office_ip":"10.0.1.10"}'
• fga tuple write --store-id=01H0H015178Y2V4CX10C2KGHF4 agent:alice-claude can_call tool:slack_send_message --condition-expression "channel_name == '#product-announcements'" --condition-parameters '{"channel_name":"string"}'
• fga tuple write --store-id=01H0H015178Y2V4CX10C2KGHF4 --model-id=01GXSA8YR785C4FYS3C0RTG7B1 --file tuples.json
• fga tuple write --store-id=01H0H015178Y2V4CX10C2KGHF4 --file tuples.csv --max-rps 10
• fga tuple write --store-id=01H0H015178Y2V4CX10C2KGHF4 --file tuples.csv --on-duplicate ignore

{
  "successful": [
    {
      "object":"document:roadmap",
      "relation":"writer",
      "user":"user:annie"
    }
  ],
}

fga tuple write --store-id=01H0H015178Y2V4CX10C2KGHF4 --file tuples.json

If using a csv file, the format should be:

user_type,user_id,user_relation,relation,object_type,object_id,condition_name,condition_context
folder,product,,parent,folder,product-2021,inOfficeIP,"{""ip_addr"":""10.0.0.1""}"

If using a yaml file, the format should be:

- user: folder:5
  relation: parent
  object: folder:product-2021
- user: folder:product-2021
  relation: parent
  object: folder:product-2021Q1

If using a jsonl file, the format should be:

{"user": "user:anne", "relation": "owner", "object": "folder:product"}
{"user": "folder:product", "relation": "parent", "object": "folder:product-2021", "condition": {"name": "inOfficeIP", "context": {"ip_addr": "10.0.0.1"}}}
{"user": "user:beth", "relation": "viewer", "object": "folder:product-2021"}

If using a json file, the format should be:

[
  {
    "user": "user:anne",
    "relation": "owner",
    "object": "folder:product"
  },
  {
    "user": "folder:product",
    "relation": "parent",
    "object": "folder:product-2021"
  },
  {
    "user": "user:beth",
    "relation": "viewer",
    "object": "folder:product-2021"
  }
]

{
  "successful": [
    {
      "object":"document:roadmap",
      "relation":"writer",
      "user":"user:annie"
    }
  ],
  "failed": [
    {
      "tuple_key": {
        "object":"document:roadmap",
        "relation":"writer",
        "user":"carl"
      },
      "reason":"Write validation error ..."
    }
  ],
  "failed_count": 1,
  "successful_count": 1,
  "total_count": 2
}

{
  "failed": [
    {
      "tuple_key": {
        "object":"document:roadmap",
        "relation":"writer",
        "user":"carl"
      },
      "reason":"Write validation error ..."
    }
  ],
  "failed_count": 1,
  "successful_count": 1,
  "total_count": 2
}

In some cases you could want to retry failed tuples (e.g. network connectivity error). To achieve that, you can direct the output to a file:

fga tuple write --file tuples.json' --hide-imported-tuples > results.json

Then, process the file with jq to convert it to format that you can send the CLI again:

jq -c '[.failed[] | {user: .tuple_key.user, relation: .tuple_key.relation, object: .tuple_key.object}]' result.json > failed_tuples.json

fga tuple write --file failed_tuples.json' --hide-imported-tuples

fga tuple delete --store-id=

• <user>: User
• <relation>: Relation
• <object>: Object
• --store-id: Specifies the store id
• --model-id: Specifies the model id to target (optional)
• --file: Specifies the file name, yaml, json, and jsonl files are supported
• --max-tuples-per-write: Max tuples to send in a single write (optional, default=1)
• --max-parallel-requests: Max requests to send in parallel (optional, default=4)
• --on-missing: Behavior when a tuple to be deleted does not exist. Options are:
  • ignore: Skip the tuple and do not return an error. Default when importing via a file.
  • error: Return an error for the tuple. Default when deleting a single tuple via arguments.

• fga tuple delete --store-id=01H0H015178Y2V4CX10C2KGHF4 user:anne can_view document:roadmap
• fga tuple delete --store-id=01H0H015178Y2V4CX10C2KGHF4 user:anne can_view document:roadmap --on-missing ignore

{}

fga tuple delete --store-id=01H0H015178Y2V4CX10C2KGHF4 --file tuples.json

{
  "successful": [
    {
      "object":"document:roadmap",
      "relation":"writer",
      "user":"user:annie"
    }
  ],
  "failed": [
    {
      "tuple_key": {
        "object":"document:roadmap",
        "relation":"writer",
        "user":"carl"
      },
      "reason":"Write validation error ..."
    }
  ]
}

If you want to delete all the tuples in a store, you can use the following code:

fga tuple read --output-format=simple-json --max-pages=0 > tuples.json
fga tuple delete --file tuples.json

fga tuple read [--user=] [--relation=] [--object=] --store-id=

• --store-id: Specifies the store id
• --user: User
• --relation: Relation
• --object: Object
• --max-pages: Max number of pages to get. Set to 0 to get all pages. (default 20)
• --page-size: Number of tuples to return per page. Defaults to 100 when max-pages=0, or 50 otherwise. Max is 100.
• --output-format: Can be csv, yaml, json or simple-json. Use simple-json for a simpler json format that can be piped to the write and delete commands

fga tuple read --store-id=01H0H015178Y2V4CX10C2KGHF4 --user user:anne --relation can_view --object document:roadmap

{
  "tuples": [
    {
      "key": {
        "object": "document:roadmap",
        "relation": "can_view",
        "user": "user:anne"
      },
      "timestamp": "2023-07-06T15:12:55.080666875Z"
    }
  ]
}

[
  {
    "object": "document:roadmap",
    "relation": "can_view",
    "user": "user:anne"
  }
]

If you want to transform this output in a way that can be then imported using the fga tuple write you can run

fga tuple read --output-format=simple-json --max-pages 0 > tuples.json
fga tuple write --file tuples.json

fga tuple changes --type --store-id=

• --store-id: Specifies the store id
• --type: Restrict to a specific type (optional)
• --start-time: Return changes since a specified time (optional)
• --max-pages: Max number of pages to retrieve (default: 20)
• --continuation-token: Continuation token to start changes from

fga tuple changes --store-id=01H0H015178Y2V4CX10C2KGHF4 --type=document --continuation-token=M3w=

{
  "changes": [
    {
      "operation": "TUPLE_OPERATION_WRITE",
      "timestamp": "2023-07-06T15:12:40.294950382Z",
      "tuple_key": {
        "object": "document:roadmap",
        "relation": "can_view",
        "user": "user:anne"
      }
    }
  ],
  "continuation_token":"NHw="
}

• query

fga query check [--condition] [--contextual-tuple "<user> <relation> <object>"]* --store-id= [--model-id=]

• --store-id: Specifies the store id
• --model-id: Specifies the model id to target (optional)
• --contextual-tuple: Contextual tuples (optional)
• --context: Condition context (optional)
• --consistenc