### Create OpenFGA Store CLI Examples

Source: https://github.com/openfga/cli/blob/main/_autodocs/api-reference/store-commands.md

Examples demonstrating how to create an OpenFGA store using the CLI. Covers creating a store with only a name, with an authorization model, and capturing the store ID for subsequent use.

```bash
# Create store with name only
fga store create --name "Production Store"

# Create store with authorization model
fga store create --name "Production Store" --model ./model.fga --format fga

# Output to get store ID
export STORE_ID=$(fga store create --name "Demo" | jq -r .store.id)
```

--------------------------------

### No Authentication Example

Source: https://github.com/openfga/cli/blob/main/_autodocs/configuration.md

Example of listing stores without any authentication, specifying only the API URL.

```bash
fga store list --api-url http://localhost:8080
```

--------------------------------

### Configuration File Example

Source: https://github.com/openfga/cli/blob/main/_autodocs/configuration.md

Example of a YAML configuration file (`~/.fga.yaml`) showing various settings including API URL, token, client credentials, scopes, custom headers, and debug mode.

```yaml
# ~/.fga.yaml
api-url: https://api.fga.example
api-token: "my-secret-token"
client-id: "optional-client-id"
client-secret: "optional-client-secret"
api-scopes:
  - "openid"
  - "profile"
custom-headers:
  - "X-Custom-Header: custom-value"
debug: false

```

--------------------------------

### Install OpenFGA CLI with Go

Source: https://github.com/openfga/cli/blob/main/README.md

Install the OpenFGA CLI directly using the Go toolchain. Ensure your Go environment is set up correctly.

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

--------------------------------

### List Relations Command Example

Source: https://github.com/openfga/cli/blob/main/README.md

Basic example of the `list-relations` command to find relations for a user on a document.

```bash
fga query list-relations --store-id=01H0H015178Y2V4CX10C2KGHF4 user:anne document:roadmap
```

--------------------------------

### List Users Command Example

Source: https://github.com/openfga/cli/blob/main/README.md

Basic example of listing users for a given object and relation. Requires store ID, object, relation, and user filter.

```bash
fga query list-users --store-id=01H0H015178Y2V4CX10C2KGHF4 --object document:roadmap --relation can_view --user-filter user
```

--------------------------------

### List Objects Command Example

Source: https://github.com/openfga/cli/blob/main/README.md

Basic example of the `list-objects` command to find documents a user can view.

```bash
fga query list-objects --store-id=01H0H015178Y2V4CX10C2KGHF4 user:anne can_view document
```

--------------------------------

### OpenFGA CLI Configuration Example (Auth0)

Source: https://github.com/openfga/cli/blob/main/README.md

Example configuration for the OpenFGA CLI when authenticating with Auth0. This includes API URL, client credentials, and store ID.

```yaml
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
```

--------------------------------

### Install OpenFGA CLI on Alpine Linux

Source: https://github.com/openfga/cli/blob/main/README.md

Install the OpenFGA CLI on Alpine Linux systems by downloading and installing the .apk package.

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

--------------------------------

### Install OpenFGA CLI on Debian-based Linux

Source: https://github.com/openfga/cli/blob/main/README.md

Install the OpenFGA CLI on Debian or Ubuntu systems by downloading and installing the .deb package.

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

--------------------------------

### Install OpenFGA CLI on Fedora-based Linux

Source: https://github.com/openfga/cli/blob/main/README.md

Install the OpenFGA CLI on Fedora systems by downloading and installing the .rpm package.

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

--------------------------------

### Install OpenFGA CLI with Scoop on Windows

Source: https://github.com/openfga/cli/blob/main/README.md

Use this command to install the OpenFGA CLI on Windows using the Scoop package manager.

```shell
scoop install openfga
```

--------------------------------

### Basic Store File Example

Source: https://github.com/openfga/cli/blob/main/docs/STORE_FILE.md

A fundamental OpenFGA store file defining the model, relationships, and a basic permission check test.

```yaml
name: "Document Management"
model_file: "./authorization-model.fga"
tuple_file: "./relationships.yaml"
tests:
  - name: "basic-permissions"
    check:
      - user: user:alice
        object: document:readme
        assertions:
          viewer: true
          editor: false
```

--------------------------------

### Setup OpenFGA in CI/CD with FGA CLI

Source: https://github.com/openfga/cli/blob/main/_autodocs/USAGE_PATTERNS.md

Automate OpenFGA environment setup in CI/CD pipelines. This script exports necessary environment variables, creates a store if it doesn't exist, imports the authorization model, and runs model tests.

```bash
#!/bin/bash
# .github/scripts/setup-fga.sh

set -e

# Export for all FGA commands
export FGA_API_URL="${FGA_API_URL:-http://localhost:8080}"
export FGA_STORE_ID="${FGA_STORE_ID}"
export FGA_API_TOKEN="${FGA_API_TOKEN}"

# Create store if not exists
if [ -z "$FGA_STORE_ID" ]; then
    STORE=$(fga store create --name "CI Store")
    export FGA_STORE_ID=$(echo "$STORE" | jq -r '.store.id')
fi

# Import auth model
fga model write ./authorization-model.fga

# Run tests
fga model test --file ./tests.yaml

echo "FGA setup complete"
echo "STORE_ID=$FGA_STORE_ID"
```

--------------------------------

### List Objects Command Examples

Source: https://github.com/openfga/cli/blob/main/_autodocs/api-reference/query-commands.md

Demonstrates how to use the 'fga query list-objects' command to find objects a user has a specific relation with. Examples include basic usage, filtering by context, and exporting the results.

```bash
# List documents alice can view
fga query list-objects user:alice viewer document --store-id "01H4..."

```

```bash
# List projects bob can edit
fga query list-objects user:bob editor project --store-id "01H4..."

```

```bash
# List with context
fga query list-objects user:alice viewer document \
  --store-id "01H4..." \
  --context '{"office":"US"}'

```

```bash
# Count accessible objects
fga query list-objects user:alice viewer document --store-id "01H4..." \
  | jq '.objects | length'

```

```bash
# Export object list
fga query list-objects user:alice viewer document --store-id "01H4..." \
  | jq -r '.objects[]'

```

--------------------------------

### OpenFGA Store File Structure Example

Source: https://github.com/openfga/cli/blob/main/docs/STORE_FILE.md

Illustrates the complete structure of an OpenFGA store configuration file, including metadata, model, tuples, and tests.

```yaml
name: "Store Name"                    # Required: Name of the store
model_file: "./model.fga"             # Path to authorization model file
model: |                              # OR inline model definition
  model
    schema 1.1
  type user
  # ... more model definitions

tuple_file: "./tuples.yaml"           # Path to tuples file  
tuples:                               # OR inline tuples
  - user: user:anne
    relation: viewer
    object: document:1

tests:                                # Test definitions
  - name: "test-name"
    description: "Test description"   # Optional
    tuple_file: "./test-tuples.yaml"  # Test-specific tuples file
    tuples:                           # OR inline test tuples
      - user: user:bob
        relation: editor
        object: document:2
    check:                            # Authorization checks
      - user: user:anne
        object: document:1
        context:                      # Optional context for ABAC
          timestamp: "2023-05-03T21:25:23+00:00"
        assertions:
          viewer: true
          editor: false
      - users:                        # Group users with same expected results
          - user:bob
          - user:charlie
        object: document:2
        assertions:
          viewer: true
    list_objects:                     # List objects tests
      - user: user:anne
        type: document
        context:                      # Optional context
          timestamp: "2023-05-03T21:25:23+00:00"
        assertions:
          viewer:
            - document:1
            - document:2
    list_users:                       # List users tests
      - object: document:1
        user_filter:
          - type: user
        context:                      # Optional context
          timestamp: "2023-05-03T21:25:23+00:00"
        assertions:
          viewer:
            users:
              - user: anne
              - user: bob
```

--------------------------------

### Check Command Example

Source: https://github.com/openfga/cli/blob/main/README.md

Basic example of the `check` command to verify a user's permission on an object.

```bash
fga query check --store-id=01H0H015178Y2V4CX10C2KGHF4 user:anne can_view document:roadmap
```

--------------------------------

### Build OpenFGA CLI from Source

Source: https://github.com/openfga/cli/blob/main/README.md

Build the OpenFGA CLI executable using Go. Alternatively, if 'make' is installed, the 'make build' command can be used.

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

```bash
make build
```

--------------------------------

### Expand Response Example

Source: https://github.com/openfga/cli/blob/main/README.md

Example JSON response for an `expand` query, showing the hierarchical structure of relationships.

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

--------------------------------

### Example of Using Custom Headers Flag

Source: https://github.com/openfga/cli/blob/main/README.md

Demonstrates how to use the --custom-headers flag to send multiple custom headers with an OpenFGA CLI command.

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

--------------------------------

### Check Response Example

Source: https://github.com/openfga/cli/blob/main/README.md

Example JSON response for a successful `check` query, indicating whether the action is allowed.

```json
{
    "allowed": true,
}
```

--------------------------------

### List Objects Response Example

Source: https://github.com/openfga/cli/blob/main/README.md

Example JSON response for a `list-objects` query, returning a list of object IDs.

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

--------------------------------

### Import Store Data using OpenFGA CLI

Source: https://github.com/openfga/cli/blob/main/_autodocs/api-reference/store-commands.md

Examples demonstrating how to import store data using the `fga store import` command. Covers importing to a new store, an existing store, and with custom settings.

```bash
# Import to new store
fga store import --file store-data.yaml
```

```bash
# Import to existing store
fga store import --store-id "01H4P8Z95KTXXEP6Z03T75Q984" --file store-data.yaml
```

```bash
# Import with custom settings
fga store import --file store-data.yaml \
  --max-tuples-per-write 50 \
  --max-parallel-requests 5
```

--------------------------------

### Install OpenFGA CLI with Homebrew

Source: https://github.com/openfga/cli/blob/main/README.md

Use this command to install the OpenFGA CLI on macOS using the Homebrew package manager.

```shell
brew install openfga/tap/fga
```

--------------------------------

### OpenFGA CLI Model Write - Stdin Example

Source: https://github.com/openfga/cli/blob/main/_autodocs/api-reference/model-commands.md

Illustrates writing an authorization model to OpenFGA by piping the model content from stdin using the CLI.

```bash
# Write from stdin
cat model.fga | fga model write --store-id "01H4P8Z95KTXXEP6Z03T75Q984"
```

--------------------------------

### OpenFGA Query Check Command Example

Source: https://github.com/openfga/cli/blob/main/_autodocs/api-reference/query-commands.md

Demonstrates how to perform authorization checks using the `fga query check` command. Supports simple checks, contextual tuples, query context, and consistency preferences.

```bash
# Simple check
fga query check user:alice viewer document:roadmap --store-id "01H4..."

```

```bash
# Check with query context
fga query check user:alice viewer document:roadmap \
  --store-id "01H4..." \
  --context '{"ip_address":"10.0.0.1"}'

```

```bash
# Check with contextual tuple
fga query check user:alice viewer document:roadmap \
  --store-id "01H4..." \
  --contextual-tuple "team:engineering#member owner document:roadmap"

```

```bash
# Check with higher consistency
fga query check user:alice viewer document:roadmap \
  --store-id "01H4..." \
  --consistency "HIGHER_CONSISTENCY"

```

```bash
# Batch checks
fga query check user:alice viewer document:roadmap --store-id "01H4..."
fga query check user:bob editor document:roadmap --store-id "01H4..."

```

--------------------------------

### List Users with Contextual Tuple

Source: https://github.com/openfga/cli/blob/main/README.md

Example of listing users with an additional contextual tuple to refine the query. This is useful for complex authorization scenarios.

```bash
fga query list-users --store-id=01H0H015178Y2V4CX10C2KGHF4 --object document:roadmap --relation can_view --user-filter user --contextual-tuple "user:anne can_view folder:product"
```

--------------------------------

### List Relations Response Example

Source: https://github.com/openfga/cli/blob/main/README.md

Example JSON response for a `list-relations` query, listing the relations found for a user and object.

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

--------------------------------

### API Token Authentication Example

Source: https://github.com/openfga/cli/blob/main/_autodocs/configuration.md

Authenticate using a bearer token by providing the API URL and the API token.

```bash
fga store list --api-url https://api.fga.example --api-token "my-token"
```

--------------------------------

### ParseTupleCondition() - Go Example

Source: https://github.com/openfga/cli/blob/main/_autodocs/api-reference/internal-utilities.md

Parses tuple conditions from `--condition-name` and `--condition-context` flags. The example shows the expected structure of the resulting `RelationshipCondition` object, including name and context.

```go
condition, err := cmdutils.ParseTupleCondition(cmd)
// Result: &openfga.RelationshipCondition{
//     Name: "inOffice",
//     Context: map[string]interface{}{ "ip_address": "10.0.0.1"}
// }
```

--------------------------------

### OpenFGA CLI Model Write - FGA Format Example

Source: https://github.com/openfga/cli/blob/main/_autodocs/api-reference/model-commands.md

Demonstrates how to write an authorization model in the default FGA format from a file using the OpenFGA CLI.

```bash
# Write from file
fga model write model.fga --store-id "01H4P8Z95KTXXEP6Z03T75Q984"
```

--------------------------------

### Multi-Test Store File Example

Source: https://github.com/openfga/cli/blob/main/docs/STORE_FILE.md

Defines a comprehensive testing scenario within a single store file. Includes model and tuple file references, and multiple test cases with specific checks and assertions.

```yaml
name: "Comprehensive Testing"
model_file: "./model.fga"
tuple_file: "./base-tuples.yaml"

tests:
  - name: "admin-permissions"
    tuples:
      - user: user:admin
        relation: owner
        object: system:config
    check:
      - user: user:admin
        object: system:config
        assertions:
          owner: true
          viewer: true
    list_objects:
      - user: user:admin
        type: system
        assertions:
          owner:
            - system:config

  - name: "user-permissions" 
    tuple_file: "./user-test-tuples.yaml"
    check:
      - user: user:john
        object: document:public
        assertions:
          viewer: true
          editor: false
    list_users:
      - object: document:public
        user_filter:
          - type: user
        assertions:
          viewer:
            users:
              - user:john
              - user:jane

  - name: "condensed-checks"
    description: "Demonstrate condensed users/objects feature"
    check:
      # Test multiple users against the same object
      - object: document:shared
        users:
          - user: alice
          - user: bob
          - user: charlie
        assertions:
          viewer: true
          editor: false
      
      # Test single user against multiple objects
      - user: user:alice
        objects:
          - document:1
          - document:2
          - document:3
        assertions:
          viewer: true
          editor: false

```

--------------------------------

### JSON Tuple Format Example

Source: https://github.com/openfga/cli/blob/main/_autodocs/configuration.md

Use this JSON format to define tuples, including optional conditions with context.

```json
[
  {
    "user": "user:alice",
    "relation": "viewer",
    "object": "document:roadmap",
    "condition": {
      "name": "inOffice",
      "context": {"ip_address": "10.0.0.1"}
    }
  }
]
```

--------------------------------

### OpenFGA Model Write - FGA Format

Source: https://github.com/openfga/cli/blob/main/_autodocs/api-reference/model-commands.md

Example of an authorization model defined in the default FGA syntax.

```plaintext
type user
type document
  relations
    viewer: [user, team#member]
    owner: [user]

type team
  relations
    member: [user]
```

--------------------------------

### YAML Tuple Format Example

Source: https://github.com/openfga/cli/blob/main/_autodocs/configuration.md

This YAML format provides a human-readable way to define tuples, supporting conditions and context.

```yaml
- user: user:alice
  relation: viewer
  object: document:roadmap
  condition:
    name: inOffice
    context:
      ip_address: "10.0.0.1"
```

--------------------------------

### OpenFGA CLI Model Write - Inline FGA Format Example

Source: https://github.com/openfga/cli/blob/main/_autodocs/api-reference/model-commands.md

Shows how to write an authorization model directly inline using the FGA format with the OpenFGA CLI.

```bash
# Write inline model
fga model write "type user
type document
  relations
    viewer: [user]" \
  --store-id "01H4P8Z95KTXXEP6Z03T75Q984"
```

--------------------------------

### Clone OpenFGA CLI Repository

Source: https://github.com/openfga/cli/blob/main/README.md

Clone the OpenFGA CLI repository to your local machine and navigate into the directory. Ensure you have Go 1.20 or later installed.

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

--------------------------------

### Write Single Tuple

Source: https://github.com/openfga/cli/blob/main/_autodocs/api-reference/tuple-commands.md

Example of writing a single relationship tuple to an OpenFGA store using the CLI. Requires the store ID.

```bash
# Write single tuple
fga tuple write user:alice viewer document:roadmap --store-id "01H4..."
```

--------------------------------

### RelationshipCondition Struct Example

Source: https://github.com/openfga/cli/blob/main/_autodocs/types.md

Demonstrates how to create a RelationshipCondition object with a name and context. Used for defining conditions on relationships in OpenFGA.

```go
condition := &openfga.RelationshipCondition{
    Name: "inOffice",
    Context: map[string]interface{}{
        "ip_address": "10.0.0.1",
        "time": "business_hours",
    },
}
```

--------------------------------

### OpenFGA CLI Configuration with Custom Headers

Source: https://github.com/openfga/cli/blob/main/README.md

Example of configuring custom headers in the ~/.fga.yaml file. This allows for persistent custom headers across CLI commands.

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

--------------------------------

### List Users with User Filter and Context

Source: https://github.com/openfga/cli/blob/main/README.md

Advanced example demonstrating the use of a specific user filter (group#member) along with contextual information and consistency preference. Note the formatting for context and consistency parameters.

```bash
fga query list-users --store-id=01H0H015178Y2V4CX10C2KGHF4 --object document:roadmap --relation can_view --user-filter group#member --context '{"ip_address":"127.0.0.1"}' --consistency="HIGHER_CONSISTENCY"
```

--------------------------------

### Export Store Data and Pipe to jq

Source: https://github.com/openfga/cli/blob/main/_autodocs/api-reference/store-commands.md

This example demonstrates exporting store data and piping the YAML output to the 'jq' command for JSON processing. This is useful for further manipulation or analysis of the exported data.

```bash
# Export and pipe to another command
fga store export --store-id "01H4P8Z95KTXXEP6Z03T75Q984" | jq .
```

--------------------------------

### Client Credentials Authentication Example

Source: https://github.com/openfga/cli/blob/main/_autodocs/configuration.md

Authenticate using OAuth2 Client Credentials flow. Requires API URL, token issuer, client ID, client secret, and optionally scopes.

```bash
fga store list \
  --api-url https://api.fga.example \
  --api-token-issuer https://issuer.example \
  --client-id my-client \
  --client-secret my-secret \
  --api-scopes "openid profile email"
```

--------------------------------

### ParseQueryContext() - Example Usage

Source: https://github.com/openfga/cli/blob/main/_autodocs/api-reference/internal-utilities.md

Shows how to use the `--context` flag to provide JSON-formatted query context. This context can include arbitrary key-value pairs for use in query evaluations.

```bash
--context '{"ip_address":"10.0.0.1","time":"business_hours"}'
```

--------------------------------

### Run OpenFGA CLI with Docker

Source: https://github.com/openfga/cli/blob/main/README.md

Pull the OpenFGA CLI Docker image and run it interactively. This is useful for testing or running commands without local installation.

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

--------------------------------

### CLI Response for Tuple Write

Source: https://github.com/openfga/cli/blob/main/README.md

Example of a successful response from the `fga tuple write` command when tuples are written directly or from a file. It details successful and failed writes.

```json
{
  "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
}
```

--------------------------------

### Using Default and Explicit Configuration Files

Source: https://github.com/openfga/cli/blob/main/_autodocs/USAGE_PATTERNS.md

Demonstrates how to use the OpenFGA CLI with its default configuration and how to explicitly specify a configuration file.

```bash
# Use default config
fga store list

# Or explicit
fga --config ~/.fga.yaml store list
```

--------------------------------

### Parse Results with jq (Count Users)

Source: https://github.com/openfga/cli/blob/main/_autodocs/api-reference/query-commands.md

This example demonstrates using `jq` to count the total number of users returned by the 'list-users' command. This is a common use case for auditing or reporting purposes.

```bash
# Count users with access
fga query list-users document:roadmap viewer --store-id "01H4..." \
  | jq '.users | length'
```

--------------------------------

### Integrate OpenFGA CLI with Docker

Source: https://github.com/openfga/cli/blob/main/_autodocs/USAGE_PATTERNS.md

Use the official OpenFGA CLI Docker image to validate and transform authorization models. This example demonstrates setting the working directory, copying project files, and running validation and transformation commands.

```dockerfile
FROM openfga/cli:latest

WORKDIR /app

COPY . .

RUN fga model validate model.fga
RUN fga model transform model.fga --to-format json
```

--------------------------------

### Instantiate and Configure OpenFGA Client

Source: https://github.com/openfga/cli/blob/main/_autodocs/api-reference/internal-utilities.md

Demonstrates how to create a ClientConfig instance with specific API details and then use it to obtain an OpenFGA SDK client. Handles potential errors during client initialization.

```go
config := fga.ClientConfig{
    ApiUrl:       "https://api.fga.example",
    StoreID:      "01H4P8Z95KTXXEP6Z03T75Q984",
    APIToken:     "my-token",
    Debug:        true,
}
client, err := config.GetFgaClient()
if err != nil {
    log.Fatal(err)
}
```

--------------------------------

### Check Relationship with Context and Consistency

Source: https://github.com/openfga/cli/blob/main/README.md

Perform a `check` operation specifying a store ID, user, relation, and object. This example also includes condition context and a higher consistency preference.

```bash
fga query check --store-id="01H4P8Z95KTXXEP6Z03T75Q984" user:anne can_view document:roadmap --context '{"ip_address":"127.0.0.1"}' --consistency="HIGHER_CONSISTENCY"
```

--------------------------------

### Import OpenFGA Store with Model and Tuples

Source: https://github.com/openfga/cli/blob/main/_autodocs/USAGE_PATTERNS.md

Create a local OpenFGA store configuration in YAML, including the model and initial tuples, and then import it.

```bash
cat > store.yaml << 'EOF'
name: "Development Store"
model: |
  type user
  type document
    relations
      viewer: [user, team#member]
      editor: [user]
  type team
    relations
      member: [user]

tuples:
  - user: "user:alice"
    relation: "viewer"
    object: "document:roadmap"
  - user: "user:bob"
    relation: "editor"
    object: "document:roadmap"
  - user: "team:engineering#member"
    relation: "viewer"
    object: "document:api-spec"

tests:
  - name: "Alice can view roadmap"
    check:
      - user: "user:alice"
        object: "document:roadmap"
        relation: "viewer"
        assertions:
          "viewer": true
  - name: "Bob cannot view api-spec"
    check:
      - user: "user:bob"
        object: "document:api-spec"
        relation: "viewer"
        assertions:
          "viewer": false
EOF

# Import store
fga store import --file store.yaml
```

--------------------------------

### Handling Missing Resources with Bash

Source: https://github.com/openfga/cli/blob/main/_autodocs/USAGE_PATTERNS.md

This bash script checks if an OpenFGA store exists using `fga store get`. If the store is not found (exit code non-zero), it proceeds to create a new store using `fga store create`.

```bash
#!/bin/bash

# Check if store exists
STORE=$(fga store get --store-id "$STORE_ID" 2>/dev/null)
if [ $? -ne 0 ]; then
    echo "Store not found, creating..."
    STORE_ID=$(fga store create --name "New Store" | jq -r '.store.id')
fi

echo "Using store: $STORE_ID"
```

--------------------------------

### Create a Store using a Model File

Source: https://github.com/openfga/cli/blob/main/README.md

Create a new store and automatically set its name based on the provided model file. The response contains store and model details.

```bash
fga store create --model Model.fga
```

```json
{
  "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"
  }
}
```

--------------------------------

### Create an OpenFGA Store

Source: https://github.com/openfga/cli/blob/main/README.md

Command to create a new OpenFGA store. Requires a name for the store.

```bash
fga store create --name="FGA Demo Store"
```

--------------------------------

### Get a Specific OpenFGA Store

Source: https://github.com/openfga/cli/blob/main/README.md

Retrieve details for a specific OpenFGA store using its ID.

```bash
fga store get --store-id=01H0H015178Y2V4CX10C2KGHF4
```

--------------------------------

### Model Get Command

Source: https://github.com/openfga/cli/blob/main/_autodocs/api-reference/model-commands.md

Retrieves a specific authorization model by its ID or the latest model if no ID is provided.

```APIDOC
## Model Get Command

Get a specific authorization model.

### Usage
`fga model get --store-id <id> [--model-id <id>] [flags]`

### Parameters
#### Query Parameters
- **store-id** (string) - Required - Store identifier
- **model-id** (string) - Optional - Model ID (uses latest if omitted)

### Returns
- Authorization model object containing:
  - `id`: Model identifier
  - `created_at`: Creation timestamp
  - `schema_version`: Schema version
  - `type_definitions`: Complete model definition
  - `conditions`: Condition definitions (if any)

### Error Cases
- Model not found → authorization model not found error
- Invalid model ID → validation error
- Store not found → store not found error

### Example
```bash
# Get latest model
fga model get --store-id "01H4P8Z95KTXXEP6Z03T75Q984"

# Get specific model version
fga model get --store-id "01H4P8Z95KTXXEP6Z03T75Q984" \
  --model-id "01H4P91JHVEX7XVFWZ8Q8T7Z1A"
```
```

--------------------------------

### Import an OpenFGA Store

Source: https://github.com/openfga/cli/blob/main/README.md

Import an OpenFGA store configuration from a specified file. The file should be in YAML format.

```bash
fga store import --file store.fga.yaml
```

--------------------------------

### Staging Environment Configuration

Source: https://github.com/openfga/cli/blob/main/_autodocs/USAGE_PATTERNS.md

Shows how to create and use a separate configuration file for a staging environment, overriding default settings. It also illustrates using environment variables for configuration.

```bash
# Create staging config
cat > ~/.fga-staging.yaml << 'EOF'
api-url: https://staging-api.fga.example
api-token: staging-token-here
debug: true
EOF

# Use staging
fga --config ~/.fga-staging.yaml store list

# Or use env vars
export FGA_API_URL="https://staging-api.fga.example"
export FGA_API_TOKEN="staging-token"
fga store list
```

--------------------------------

### Import a Complete Store

Source: https://github.com/openfga/cli/blob/main/_autodocs/README.md

Use this command to import an entire store configuration from a YAML file. Ensure the file path is correct.

```bash
fga store import --file store.yaml
```

--------------------------------

### Expand Relation Example

Source: https://github.com/openfga/cli/blob/main/_autodocs/api-reference/query-commands.md

Basic usage of the expand command to see who has a specific relation with an object. Requires a store ID.

```bash
# Expand relation
fga query expand viewer document:roadmap --store-id "01H4..."
```

```bash
# Expand owner relation
fga query expand owner document:roadmap --store-id "01H4..."
```

--------------------------------

### Create OpenFGA Store

Source: https://github.com/openfga/cli/blob/main/_autodocs/USAGE_PATTERNS.md

Create a new OpenFGA store, optionally with an initial authorization model. The store ID is captured for subsequent commands.

```bash
# Create empty store
STORE_ID=$(fga store create --name "My App" | jq -r '.store.id')

# Or create with initial model
STORE_ID=$(fga store create \
  --name "My App" \
  --model ./auth-model.fga \
  | jq -r '.store.id')

# Save for later use
export FGA_STORE_ID=$STORE_ID
```

--------------------------------

### Run OpenFGA CLI

Source: https://github.com/openfga/cli/blob/main/README.md

Execute the OpenFGA CLI after building it from source.

```bash
./dist/fga
```

--------------------------------

### OpenFGA Model Write - JSON Format

Source: https://github.com/openfga/cli/blob/main/_autodocs/api-reference/model-commands.md

Example of an authorization model defined in JSON format, suitable for API or CLI input.

```json
{
  "schema_version": "1.1",
  "type_definitions": [
    {
      "type": "user"
    },
    {
      "type": "document",
      "relations": {
        "viewer": {"union": {"child": [{"this": {}}, {"computedUserset": {"object": "team", "relation": "member"}}]}},
        "owner": {"this": {}}
      }
    }
  ]
}
```

--------------------------------

### Create a Store with a Specific Name

Source: https://github.com/openfga/cli/blob/main/README.md

Use this command to create a new store and assign it a specific name. The response includes the store's ID, name, and timestamps.

```bash
fga store create --name "FGA Demo Store"
```

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

--------------------------------

### Custom Headers Example

Source: https://github.com/openfga/cli/blob/main/_autodocs/configuration.md

Include custom HTTP headers in requests by repeating the `--custom-headers` flag. The format is `Header-Name: value`.

```bash
fga store list \
  --api-url http://localhost:8080 \
  --custom-headers "X-Custom-Header: value1" \
  --custom-headers "Authorization: Bearer token2"
```

--------------------------------

### Store Get Command

Source: https://github.com/openfga/cli/blob/main/_autodocs/api-reference/store-commands.md

Retrieves details for a specific store using its identifier. Returns a store object with ID, name, and timestamps.

```APIDOC
## Store Get Command

### Description
Get details of a specific store.

### Usage
`fga store get --store-id <id> [flags]`

### Parameters
#### Path Parameters
- **store-id** (string) - Required - Store identifier

### Returns
- Store object containing:
  - `id`: Store identifier
  - `name`: Store name
  - `created_at`: Creation timestamp
  - `updated_at`: Last update timestamp

### Error Cases
- Store ID not found → store not found error
- Invalid store ID format → validation error
- API connection failure → SDK error

### Example
```bash
# Get specific store
fga store get --store-id "01H4P8Z95KTXXEP6Z03T75Q984"

# Get store name
fga store get --store-id "01H4P8Z95KTXXEP6Z03T75Q984" | jq -r '.name'
```
```

--------------------------------

### List OpenFGA Stores

Source: https://github.com/openfga/cli/blob/main/README.md

Command to list all available OpenFGA stores.

```bash
fga store list
```

--------------------------------

### List All Relations for a User and Object

Source: https://github.com/openfga/cli/blob/main/_autodocs/api-reference/query-commands.md

Use this command to list all relations a specific user has with a given object in your OpenFGA store. Ensure you provide the user, object, and store ID.

```bash
# List all alice's relations with document:roadmap
fga query list-relations user:alice document:roadmap --store-id "01H4..."
```

--------------------------------

### Get Latest Authorization Model

Source: https://github.com/openfga/cli/blob/main/README.md

Retrieves the latest authorization model for a given store. If no model ID is specified, the most recent one is returned.

```bash
fga model get --store-id=01H0H015178Y2V4CX10C2KGHF4
```

--------------------------------

### Get Specific Authorization Model

Source: https://github.com/openfga/cli/blob/main/_autodocs/api-reference/model-commands.md

Retrieves a specific authorization model by its ID or the latest model if no ID is provided. Requires a store ID.

```bash
# Get latest model
fga model get --store-id "01H4P8Z95KTXXEP6Z03T75Q984"
```

```bash
# Get specific model version
fga model get --store-id "01H4P8Z95KTXXEP6Z03T75Q984" \
  --model-id "01H4P91JHVEX7XVFWZ8Q8T7Z1A"
```

--------------------------------

### CLI Command: Store Import

Source: https://github.com/openfga/cli/blob/main/docs/STORE_FILE.md

Import a complete OpenFGA store configuration from a specified file using the `fga store import` command.

```bash
fga store import --file store.fga.yaml
```

--------------------------------

### Write and Verify OpenFGA Authorization Model

Source: https://github.com/openfga/cli/blob/main/_autodocs/USAGE_PATTERNS.md

Write an authorization model from a file to a store and then verify its retrieval. The authorization model ID is captured.

```bash
# Write model
MODEL_ID=$(fga model write ./auth-model.fga --store-id $FGA_STORE_ID \
  | jq -r '.authorization_model_id')

# Verify model
fga model get --store-id $FGA_STORE_ID --model-id $MODEL_ID
```

--------------------------------

### Delete a Store

Source: https://github.com/openfga/cli/blob/main/_autodocs/api-reference/store-commands.md

Deletes a specific store and all its associated data using its ID. An example demonstrates how to delete all stores by combining list and delete commands.

```bash
# Delete a store
fga store delete --store-id "01H4P8Z95KTXXEP6Z03T75Q984"
```

```bash
# Delete all stores (requires loop)
fga store list | jq -r '.stores[].id' | xargs -I {} fga store delete --store-id {}
```

--------------------------------

### CSV Tuple Format Example

Source: https://github.com/openfga/cli/blob/main/_autodocs/configuration.md

The CSV format is suitable for bulk imports. Ensure required headers are present and condition context is valid JSON.

```csv
user_type,user_id,user_relation,relation,object_type,object_id,condition_name,condition_context
user,alice,,viewer,document,roadmap,inOffice,"{ ""ip_addr"":""10.0.0.1"" }"
```

--------------------------------

### Get Authorization Model in JSON Format

Source: https://github.com/openfga/cli/blob/main/README.md

Retrieves a specific authorization model and formats the output as JSON. This is useful for programmatic consumption of model details.

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

--------------------------------

### Store Create Command

Source: https://github.com/openfga/cli/blob/main/_autodocs/api-reference/store-commands.md

Creates a new OpenFGA store. Optionally, an authorization model can be provided during creation. The command returns details of the created store and the authorization model if provided.

```APIDOC
## Store Create Command

### Description
Creates a new OpenFGA store with optional authorization model initialization.

### Method
`fga store create`

### Parameters
#### Flags
- **name** (string) - Required - Name for the new store
- **model** (string) - Optional - Authorization model file path or inline content
- **format** (string) - Optional - Model format: "fga", "json", or "modular" (default: "fga")

### Returns
- `CreateStoreAndModelResponse` containing:
  - `Store`: Store ID, name, creation timestamp, update timestamp
  - `Model`: (optional) Authorization model ID and creation response

### Error Cases
- Store name is empty → `required flag(s) "name" not set`
- Invalid model format → format validation error
- API connection failure → wrapped error from SDK

### Example
```bash
# Create store with name only
fga store create --name "Production Store"

# Create store with authorization model
fga store create --name "Production Store" --model ./model.fga --format fga

# Output to get store ID
export STORE_ID=$(fga store create --name "Demo" | jq -r .store.id)
```
```

--------------------------------

### Optimize Tuple Imports with FGA CLI

Source: https://github.com/openfga/cli/blob/main/_autodocs/USAGE_PATTERNS.md

Configure import settings for optimal performance. Use high concurrency for fast imports, rate limiting to respect server limits, or conservative settings for stability.

```bash
# Default: balanced
fga tuple write --file tuples.csv --store-id "$STORE_ID"
```

```bash
# Fast import (high concurrency)
fga tuple write \
  --file tuples.csv \
  --store-id "$STORE_ID" \
  --max-tuples-per-write 500 \
  --max-parallel-requests 50
```

```bash
# Rate-limited import (respect server limits)
fga tuple write \
  --file tuples.csv \
  --store-id "$STORE_ID" \
  --max-rps 100 \
  --rampup-period-in-sec 60
```

```bash
# Conservative import (stable, predictable)
fga tuple write \
  --file tuples.csv \
  --store-id "$STORE_ID" \
  --max-tuples-per-write 50 \
  --max-parallel-requests 5
```

--------------------------------

### List Relations with Specific Relation

Source: https://github.com/openfga/cli/blob/main/README.md

Use `list-relations` to find all relations a user has to a specific object. This example targets a particular relation and requires a store ID.

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

--------------------------------

### Create OpenFGA Store with Model

Source: https://github.com/openfga/cli/blob/main/_autodocs/api-reference/store-commands.md

Use this function to create a new OpenFGA store along with an authorization model. It accepts the store name, model content, and model format as parameters.

```go
type CreateStoreAndModelResponse struct {
    Store client.ClientCreateStoreResponse
    Model *client.ClientWriteAuthorizationModelResponse
}

func CreateStoreWithModel(
    ctx context.Context,
    fgaClient client.SdkClient,
    storeName string,
    inputModel string,
    inputFormat authorizationmodel.ModelFormat,
) (*CreateStoreAndModelResponse, error)
```

--------------------------------

### Display Transformed Authorization Model

Source: https://github.com/openfga/cli/blob/main/README.md

The output of the `transform` command displays the authorization model in the specified format. This example shows a model transformed into a Python-like representation.

```python
model
  schema 1.1

type user

type document
  relations
    define can_view: [user]
```

--------------------------------

### ModelFormat String Enum Example

Source: https://github.com/openfga/cli/blob/main/_autodocs/types.md

Demonstrates setting and retrieving the string representation of the ModelFormat enum. This enum is used for handling model formats in various commands.

```go
var format authorizationmodel.ModelFormat = "fga"
format.Set("json")
println(format.String()) // Output: "json"
```