OpenFGA CLI

A cross-platform CLI to interact with an OpenFGA server

About

OpenFGA is an open source Fine-Grained Authorization solution inspired by Google's Zanzibar paper. It was created by the FGA team at Auth0 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.

Resources

Installation

Brew

brew install openfga/tap/fga

Linux (deb, rpm and apk) packages

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

Docker

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

Go

note that the command will be named cli

go install github.com/openfga/cli@latest

Manually

Download the pre-compiled binaries from the releases page.

Building from Source

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

Clone the repo to a local directory, and navigate to that directory:
```
git clone https://github.com/openfga/cli.git && cd cli
```
Then use the build command:
```
go build -o ./dist/fga main.go
```
or if you have make installed, just run:
```
make build
```
Run the OpenFGA CLI with:
```
./dist/fga
```

Usage

Configuration

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

Name	Flag	CLI
Server Url	`--server-url`	`FGA_SERVER_URL`
Shared Secret	`--api-token`	`FGA_API_TOKEN`
Client ID	`--client-id`	`FGA_CLIENT_ID`
Client Secret	`--client-secret`	`FGA_CLIENT_SECRET`
Token Issuer	`--api-token-issuer`	`FGA_API_TOKEN_ISSUER`
Token Audience	`--api-audience`	`FGA_API_AUDIENCE`
Store ID	`--store-id`	`FGA_STORE_ID`
Authorization Model ID	`--model-id`	`FGA_MODEL_ID`

Commands

Stores

Description	command	parameters	example
Create a Store	`create`	`--name`	`fga store create --name="FGA Demo Store"`
List Stores	`list`		`fga store list`
Get a Store	`get`	`--store-id`	`fga store get --store-id=01H0H015178Y2V4CX10C2KGHF4`
Delete a Store	`delete`	`--store-id`	`fga store delete --store-id=01H0H015178Y2V4CX10C2KGHF4`

Create Store

Command

fga store create

Parameters

--name: Specifies the name of the store to be created

Example

fga store create --name "FGA Demo Store"

JSON Response

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

List Stores

Command

fga store list

Parameters

--max-pages: Max number of pages to retrieve (default: 20)

Example

fga store list

JSON Response

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

Get Store

Command

fga store get

Parameters

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

Example

fga store get --store-id=01H0H015178Y2V4CX10C2KGHF4

JSON Response

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

Delete Store

Command

fga store delete

Parameters

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

Example

fga store delete --store-id=01H0H015178Y2V4CX10C2KGHF4

JSON Response

{}

Authorization Models

model

Description	command	parameters	example
Read Authorization Models	`list`	`--store-id`	`fga model list --store-id=01H0H015178Y2V4CX10C2KGHF4`
Write Authorization Model	`write`	`--store-id`, `--file`	`fga model write --store-id=01H0H015178Y2V4CX10C2KGHF4 --file=model.json`
Read a Single Authorization Model	`get`	`--store-id`, `--model-id`	`fga model get --store-id=01H0H015178Y2V4CX10C2KGHF4 --model-id=01GXSA8YR785C4FYS3C0RTG7B1`

Read Authorization Models

Command

fga model list

Parameters

--store-id: Specifies the store id
--max-pages: Max number of pages to retrieve (default: 20)

Example

fga model list --store-id=01H0H015178Y2V4CX10C2KGHF4

JSON Response

[{
    "schema_version": "1.1",
    "id": "01GXSA8YR785C4FYS3C0RTG7B1",
    "type_definitions": [
      {"type": "user"},
      // { ... }
    ],
},
// { ... }
]

Write Authorization Model

Command

fga model write

Parameters

--store-id: Specifies the store id
--file: Specifies the file containing the model in JSON format

Example

fga model write --store-id=01H0H015178Y2V4CX10C2KGHF4 --file=model.json
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"}'

JSON Response

{
  "authorization_model_id":"01GXSA8YR785C4FYS3C0RTG7B1"
}

Read a Single Authorization Model

Command

fga model get

Parameters

--store-id: Specifies the store id
--model-id: Specifies the model id

Example

fga model get --store-id=01H0H015178Y2V4CX10C2KGHF4 --model-id=01GXSA8YR785C4FYS3C0RTG7B1

JSON Response

{
    "schema_version": "1.1",
    "id": "01GXSA8YR785C4FYS3C0RTG7B1",
    "type_definitions": [
      {"type": "user"},
      // { ... }
    ],
}

Read the Latest Authorization Model

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

Command

fga model get

Parameters

--store-id: Specifies the store id

Example

fga model get --store-id=01H0H015178Y2V4CX10C2KGHF4

JSON Response

{
    "schema_version": "1.1",
    "id": "01GXSA8YR785C4FYS3C0RTG7B1",
    "type_definitions": [
      {"type": "user"},
      // { ... }
    ],
}

Validate an Authorization Model

Command

fga model validate

Parameters

Example

fga model validate '{"schema_version":"1.1,"type_definitions":[{"type":"user"}]}'

JSON Response

Valid model with an ID

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

Valid model without an ID

{"is_valid":true}

Invalid model with an ID

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

Invalid model without an ID

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

Relationship Tuples

tuple

Description	command	parameters	example
Write Relationship Tuples	`write`	`--store-id`, `--model-id`	`fga tuple write --store-id=01H0H015178Y2V4CX10C2KGHF4 '{"schema_version":"1.1","type_definitions":[...]}'`
Delete Relationship Tuples	`delete`	`--store-id`, `--model-id`	`fga tuple delete --store-id=01H0H015178Y2V4CX10C2KGHF4`
Read Relationship Tuples	`read`	`--store-id`, `--model-id`	`fga tuple read --store-id=01H0H015178Y2V4CX10C2KGHF4 --model-id=01GXSA8YR785C4FYS3C0RTG7B1`
Read Relationship Tuple Changes (Watch)	`changes`	`--store-id`, `--model-id`	`fga tuple changes --store-id=01H0H015178Y2V4CX10C2KGHF4 --model-id=01GXSA8YR785C4FYS3C0RTG7B1`
Import Relationship Tuples	`import`	`--store-id`, `--model-id`, `--file`	`fga tuple import --store-id=01H0H015178Y2V4CX10C2KGHF4 --model-id=01GXSA8YR785C4FYS3C0RTG7B1 --file=tuples.json`

Write Relationship Tuples

Command

fga tuple write --store-id=

Parameters

<user>: User
<relation>: Relation
<object>: Object
--store-id: Specifies the store id
--model-id: Specifies the model id to target (optional)

Example

fga tuple write --store-id=01H0H015178Y2V4CX10C2KGHF4 user:anne can_view document:roadmap

JSON Response

{}

Delete Relationship Tuples

Command

fga tuple delete --store-id=

Parameters

<user>: User
<relation>: Relation
<object>: Object
--store-id: Specifies the store id

Example

fga tuple delete --store-id=01H0H015178Y2V4CX10C2KGHF4 user:anne can_view document:roadmap

JSON Response

{}

Read Relationship Tuples

Command

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

Parameters

--store-id: Specifies the store id
--user: User
--relation: Relation
--object: Object

Example

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

JSON Response

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

Read Relationship Tuple Changes (Watch)

Command

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

Parameters

--store-id: Specifies the store id
--type: restrict to a specific type (optional)
--max-pages: Max number of pages to retrieve (default: 20)

Example

fga tuple changes --store-id=01H0H015178Y2V4CX10C2KGHF4 --type document

JSON Response

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

Import Relationship Tuples

Command

fga tuple import --store-id= [--model-id=] --file= [--max-tuples-per-write=] [--max-parallel-requests=]

Parameters

--store-id: Specifies the store id
--model-id: Specifies the model id to target (optional)
--file: Specifies the file name, yaml and json files are supported
--max-tuples-per-write: Max tuples to send in a single write (optional, default=20)
--max-parallel-requests: Max requests to send in parallel (optional, default=4)

File format should be: In YAML:

- user: user:anne
  relation: can_view
  object: document:roadmap
- user: user:beth
  relation: can_view
  object: document:roadmap

In JSON:

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

Example

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

JSON Response

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

Relationship Queries

query

Description	command	parameters	example
Check	`check`	`--store-id`, `--model-id`	`fga query check --store-id=01H0H015178Y2V4CX10C2KGHF4 user:anne can_view document:roadmap`
List Objects	`list-objects`	`--store-id`, `--model-id`	`fga query list-objects --store-id=01H0H015178Y2V4CX10C2KGHF4 user:anne can_view document`
List Relations	`list-relations`	`--store-id`, `--model-id`	`fga query list-relations --store-id=01H0H015178Y2V4CX10C2KGHF4 user:anne document`
Expand	`expand`	`--store-id`, `--model-id`	`fga query expand --store-id=01H0H015178Y2V4CX10C2KGHF4 can_view document:roadmap`

Check

Command

fga query check [--contextual-tuple " "]* --store-id= [--model-id=]

Parameters

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

Example

fga query check --store-id=01H0H015178Y2V4CX10C2KGHF4 user:anne can_view document:roadmap --contextual-tuple "user:anne can_view folder:product" --contextual-tuple "folder:product parent document:roadmap"

JSON Response

{
    "allowed": true,
}

List Objects

Command

fga query list-objects <object_type> [--contextual-tuple " "]* --store-id= [--model-id=]

Parameters

--store-id: Specifies the store id
--model-id: Specifies the model id to target (optional)
--contextual-tuple: Contextual tuples (optional) (can be multiple)

Example

fga query list-objects --store-id=01H0H015178Y2V4CX10C2KGHF4 user:anne can_view document --contextual-tuple "user:anne can_view folder:product" --contextual-tuple "folder:product parent document:roadmap"

JSON Response

{
    "objects": [
      "document:roadmap",
      "document:budget"
    ],
}

List Relations

Command

fga query list-objects [--relation ]* [--contextual-tuple " "]* --store-id= [--model-id=]

Parameters

--store-id: Specifies the store id
--model-id: Specifies the model id to target (optional)
--contextual-tuple: Contextual tuples (optional) (can be multiple)

Example

fga query list-relations --store-id=01H0H015178Y2V4CX10C2KGHF4 user:anne document:roadmap --relation can_view

JSON Response

{
    "relations": [
      "can_view"
    ],
}

Expand

Command

fga query expand --store-id= [--model-id=]

Parameters

--store-id: Specifies the store id
--model-id: Specifies the model id to target (optional)

Example

fga query expand --store-id=01H0H015178Y2V4CX10C2KGHF4 can_view document:roadmap

JSON Response

{
  "tree": {
    "root": {
      "name": "repo:openfga/openfga#reader",
      "union": {
        "nodes": [{
          "leaf": {
            "users": {
              "users": ["user:anne"]
            }
          },
          "name": "repo:openfga/openfga#reader"
        }]
      }
    }
  }
}

Contributing

See CONTRIBUTING.

Author

OpenFGA

License

This project is licensed under the Apache-2.0 license. See the LICENSE file for more info.

Name		Name	Last commit message	Last commit date
Latest commit History 172 Commits
.github		.github
cmd		cmd
internal		internal
scripts		scripts
.dev.Dockerfile		.dev.Dockerfile
.dockerignore		.dockerignore
.fossa.yml		.fossa.yml
.gitignore		.gitignore
.golangci.yaml		.golangci.yaml
.goreleaser.Dockerfile		.goreleaser.Dockerfile
.goreleaser.yaml		.goreleaser.yaml
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
Makefile		Makefile
NOTICE.txt		NOTICE.txt
README.md		README.md
go.mod		go.mod
go.sum		go.sum
main.go		main.go

License

booniepepper/cli

Folders and files

Latest commit

History

Repository files navigation

OpenFGA CLI

Table of Contents

About

Resources

Installation

Brew

Linux (deb, rpm and apk) packages

Docker

Go

Manually

Building from Source

Usage

Configuration

Commands

Stores

Create Store

Command

Parameters

Example

JSON Response

List Stores

Command

Parameters

Example

JSON Response

Get Store

Command

Parameters

Example

JSON Response

Delete Store

Command

Parameters

Example

JSON Response

Authorization Models

Read Authorization Models

Command

Parameters

Example

JSON Response

Write Authorization Model

Command

Parameters

Example

JSON Response

Read a Single Authorization Model

Command

Parameters

Example

JSON Response

Read the Latest Authorization Model

Command

Parameters

Example

JSON Response

Validate an Authorization Model

Command

Parameters

Example

JSON Response

Relationship Tuples

Write Relationship Tuples

Command

Parameters

Example

JSON Response

Delete Relationship Tuples

Command

Parameters

Example

JSON Response

Read Relationship Tuples

Command

Packages