cli

README

OpenFGA CLI

A cross-platform CLI to interact with an OpenFGA server

Table of Contents

• About OpenFGA
• Resources
• Installation
• Building from Source
• Usage
  • Configuration
  • Commands
    • Stores
      • List All Stores
      • Create 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
      • Transform an Authorization Model
    • Relationship Tuples
      • Read Relationship Tuple Changes (Watch)
      • Read Relationship Tuples
      • Create Relationship Tuples
      • Delete Relationship Tuples
    • Relationship Queries
      • Check
      • Expand
      • List Objects
      • List Relations
• Contributing
• License

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

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

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.

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 main.go
   

   or if you have make installed, just run:

   make build
   

3. 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	~/.fga.yaml
Server Url	--server-url	FGA_SERVER_URL	server-url
Shared Secret	--api-token	FGA_API_TOKEN	api-token
Client ID	--client-id	FGA_CLIENT_ID	client-id
Client Secret	--client-secret	FGA_CLIENT_SECRET	client-secret
Token Issuer	--api-token-issuer	FGA_API_TOKEN_ISSUER	api-token-issuer
Token Audience	--api-audience	FGA_API_AUDIENCE	api-audience
Store ID	--store-id	FGA_STORE_ID	store-id
Authorization Model ID	--model-id	FGA_MODEL_ID	model-id

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:

client-id: 4Zb..UYjaHreLKOJuU8
client-secret: J3...2pBwiauD
api-audience: https://api.us1.fga.dev/
api-token-issuer: fga.us.auth0.com

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: 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 or OpenFGA format (optional).
• --format : Authorization model input format. Can be "fga" or "json" (optional, defaults to the model file extension if present).

Example

fga store create --name "FGA Demo Store"

Response

{
    "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

Response

{
  "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)

List Stores

Command

fga store list

Parameters

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

Example

fga store list

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

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

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.fga
Read a Single Authorization Model	get	--store-id, --model-id	fga model get --store-id=01H0H015178Y2V4CX10C2KGHF4 --model-id=01GXSA8YR785C4FYS3C0RTG7B1
Transform an Authorization Model	transform	--file, --input-format	fga model transform --file model.json

Read Authorization Models

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

Command

fga model list

Parameters

• --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.

Example

fga model list --store-id=01H0H015178Y2V4CX10C2KGHF4

Response

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

Write Authorization Model

Command

fga model write

Parameters

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

Example

• fga model write --store-id=01H0H015178Y2V4CX10C2KGHF4 --file=model.fga
• 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

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
• --format: Authorization model output format. Can be "fga" or "json" (default fga).
• --field: Fields to display, choices are: id, created_at and model. Default is model.

Example

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

Response

model
  schema 1.1

type user

type document
  relations
    define can_view: [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

Response

model
  schema 1.1

type user

type document
  relations
    define can_view: [user]

Transform an Authorization Model

Command

fga model transform

Parameters

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

Example

fga model transform --file model.json

Response

model
  schema 1.1

type user

type document
  relations
    define can_view: [user]

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

Documentation

Overview

Copyright © 2023 OpenFGA

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.