openfga-cli

module
v0.267.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 3, 2026 License: MIT

README

the interactive ofga playground TUI

ofga

A modern CLI & TUI for OpenFGA.

Manage stores, authorization models, relationship tuples, and run checks from your terminal, or explore everything interactively in a full-screen TUI.

Quick start · The TUI · Commands · Configuration · Docs · Contributing

CI CodeQL Go Report Card Release Go version GHCR Conventional Commits PRs welcome

📑 Table of contents

✨ What is this?

ofga is a single, dependency-free binary that gives you two ways to work with an OpenFGA server:

  • 🧰 A scriptable CLI: create stores, write and inspect authorization models, manage relationship tuples, run check/list-objects/list-users/list-relations, and run assertion suites. Read commands provide consistent JSON/YAML output, tabular commands support --plain, and failures return meaningful exit codes.
  • 🖥 A full-screen TUI: launch it by running ofga with no arguments. Browse stores, visualize a model as a colored relation graph, edit tuples, run queries and expand their resolution trees, and manage assertions, all with the keyboard or the mouse.

It talks to any OpenFGA-compatible server and reuses your connection profiles so you can switch between local, staging, and production in one flag.

Naming: the official OpenFGA CLI is fga. This is a separate, independent reimagining focused on ergonomics and an interactive TUI, distributed as ofga. It is not affiliated with OpenFGA.

🚀 Quick start

# 1. Start a local OpenFGA server in another terminal
docker run --rm --name openfga -p 8080:8080 openfga/openfga run

# 2. Point ofga at it (guided; uses http://localhost:8080 by default)
ofga init

# 3. Create a store and make it active
ofga stores create demo --use

# 4. Write an authorization model
cat > model.fga <<'FGA'
model
  schema 1.1

type user

type document
  relations
    define viewer: [user]
FGA
ofga model write --file model.fga
# `.fga` DSL is transformed to JSON for you. `--file` also takes a `.json`
# model, or `-` to read from stdin.

# 5. Add a relationship tuple
ofga tuples write user:anne viewer document:roadmap

# 6. Ask an authorization question
ofga query check user:anne viewer document:roadmap
# ✓ ALLOWED  user:anne viewer document:roadmap

# 7. …or explore everything interactively
ofga

Already have a server? Skip step 1 and pass its URL to ofga init.

📦 Installation

brew install sergiught/tap/ofga

curl -fsSL https://raw.githubusercontent.com/sergiught/openfga-cli/main/install.sh | bash

Full matrix (AUR, go install, Docker, source), upgrade, and uninstall → the installation guide

🖥 The interactive TUI

Run ofga with no arguments to launch the interactive playground, a keyboard- and mouse-driven cockpit covering profiles, stores, the model graph, tuples, queries with resolution trees, and assertions. Press ? at any time for the full, context-aware keybinding overlay.

Icons adapt to your terminal automatically. If they render as ? or boxes, press ctrl+g to cycle to a plainer glyph set — see terminal glyphs.

Full TUI guide & keybinding reference → the TUI guide

📋 Command reference

Every command has a generated reference page with a live demo recording: https://sergiught.github.io/openfga-cli/reference/

📚 Documentation

🏗 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for the build/test/lint workflow and the Conventional Commits convention used for automated releases.

Report bugs and request features through GitHub Issues. Report vulnerabilities privately as described in SECURITY.md.

go build ./...
go test ./...

⚖️ License

MIT © Sergiu Ghitea. Built for the excellent OpenFGA project (not affiliated).

Directories

Path Synopsis
cmd
ofga command
Command ofga is a modern CLI and TUI for OpenFGA.
 Command ofga is a modern CLI and TUI for OpenFGA.
internal
apilog
Package apilog captures OpenFGA HTTP traffic.
 Package apilog captures OpenFGA HTTP traffic.
atomicfile
Package atomicfile writes a file by staging it next to its destination and renaming it into place only once the caller is satisfied with the contents.
 Package atomicfile writes a file by staging it next to its destination and renaming it into place only once the caller is satisfied with the contents.
cli
Package cli holds the shared dependencies threaded through every command: the logger, the loaded config, and the global flag overrides.
 Package cli holds the shared dependencies threaded through every command: the logger, the loaded config, and the global flag overrides.
client
Package client constructs a configured go-openfga client from resolved config.
 Package client constructs a configured go-openfga client from resolved config.
clierr
Package clierr centralizes how command errors map to user-facing messages and process exit codes, so main can stay a thin shell and every command surfaces failures consistently.
 Package clierr centralizes how command errors map to user-facing messages and process exit codes, so main can stay a thin shell and every command surfaces failures consistently.
command
Package command defines the shared Command abstraction used by every ofga command, mirroring the structure of task-pilot-cli: each command exposes its cobra command, registers its sub-commands, and implements its run logic.
 Package command defines the shared Command abstraction used by every ofga command, mirroring the structure of task-pilot-cli: each command exposes its cobra command, registers its sub-commands, and implements its run logic.
command/api
Package api implements `ofga api`: send a raw request to the OpenFGA API using the active profile's connection and authentication.
 Package api implements `ofga api`: send a raw request to the OpenFGA API using the active profile's connection and authentication.
command/assertions
Package assertions implements `ofga assertions`: read and write the assertion test-suite attached to an authorization model, and run it.
 Package assertions implements `ofga assertions`: read and write the assertion test-suite attached to an authorization model, and run it.
command/base
Package base provides the root `ofga` command: persistent flags, the help banner, and registration of every top-level sub-command.
 Package base provides the root `ofga` command: persistent flags, the help banner, and registration of every top-level sub-command.
command/configcmd
Package configcmd implements `ofga config`: inspect where ofga's configuration lives and what it resolves to.
 Package configcmd implements `ofga config`: inspect where ofga's configuration lives and what it resolves to.
command/model
Package model implements `ofga model`: write, list, inspect, and visualize authorization models (including a colored relation graph).
 Package model implements `ofga model`: write, list, inspect, and visualize authorization models (including a colored relation graph).
command/playground
Package playground implements the interactive `ofga` TUI: a full-screen, Crush-style shell for exploring a store — picking models, browsing tuples, running live checks, and visualizing the authorization model as a graph.
 Package playground implements the interactive `ofga` TUI: a full-screen, Crush-style shell for exploring a store — picking models, browsing tuples, running live checks, and visualizing the authorization model as a graph.
command/profiles
Package profiles implements `ofga profiles`: manage named connection profiles — list, switch, inspect, create, edit and remove them.
 Package profiles implements `ofga profiles`: manage named connection profiles — list, switch, inspect, create, edit and remove them.
command/query
Package query implements `ofga query`: the read-side authorization questions — check, batch-check, expand, list-objects and list-users.
 Package query implements `ofga query`: the read-side authorization questions — check, batch-check, expand, list-objects and list-users.
command/store
Package store implements `ofga stores`: create, list, inspect and delete OpenFGA stores.
 Package store implements `ofga stores`: create, list, inspect and delete OpenFGA stores.
command/tuple
Package tuple implements `ofga tuples`: write, delete, read relationship tuples and follow the changelog.
 Package tuple implements `ofga tuples`: write, delete, read relationship tuples and follow the changelog.
config
Package config loads and persists ofga configuration: a set of named connection profiles (contexts) plus the name of the active one.
 Package config loads and persists ofga configuration: a set of named connection profiles (contexts) plus the name of the active one.
configtest
Package configtest isolates the CLI's on-disk config so a test never reads or writes the developer's real one.
 Package configtest isolates the CLI's on-disk config so a test never reads or writes the developer's real one.
dsl
Package dsl provides syntax highlighting and syntax-error diagnostics for OpenFGA DSL text, built on the openfga/language ANTLR lexer and parser.
 Package dsl provides syntax highlighting and syntax-error diagnostics for OpenFGA DSL text, built on the openfga/language ANTLR lexer and parser.
fga
Package fga holds OpenFGA domain helpers shared by the CLI commands and the TUI: parsing tuple shorthand and turning an authorization model into a graph.
 Package fga holds OpenFGA domain helpers shared by the CLI commands and the TUI: parsing tuple shorthand and turning an authorization model into a graph.
modeltest
Package modeltest runs authorization-model tests declared by an ofga workspace (an ofga.yaml manifest and its *.test.yaml files).
 Package modeltest runs authorization-model tests declared by an ofga workspace (an ofga.yaml manifest and its *.test.yaml files).
output
Package output renders command results either as a styled table/summary for humans or as indented JSON for machines (--json).
 Package output renders command results either as a styled table/summary for humans or as indented JSON for machines (--json).
prompt
Package prompt provides consistent confirmation gates for destructive commands: interactive y/N (or type-to-confirm) on a terminal, and a required --force flag when running non-interactively so scripts fail safe.
 Package prompt provides consistent confirmation gates for destructive commands: interactive y/N (or type-to-confirm) on a terminal, and a required --force flag when running non-interactively so scripts fail safe.
readlimit
Package readlimit provides bounded reads for user-controlled files, stdin, and HTTP bodies.
 Package readlimit provides bounded reads for user-controlled files, stdin, and HTTP bodies.
style
Package style centralizes the lipgloss palette and reusable styles.
 Package style centralizes the lipgloss palette and reusable styles.
theme
Package theme defines named color palettes for the CLI and TUI.
 Package theme defines named color palettes for the CLI and TUI.
ui/field
Package field provides a minimal themed form: labeled text inputs with an accent bar on focus, inline validation, tab-cycled focus, and enter-to-submit.
 Package field provides a minimal themed form: labeled text inputs with an accent bar on focus, inline validation, tab-cycled focus, and enter-to-submit.
ui/icons
Package icons resolves the process-wide glyph set: auto (the default, which promotes to Nerd Font only on a positive signal), an explicit Nerd Font rung, a universal Unicode fallback, or off for decorative glyphs.
 Package icons resolves the process-wide glyph set: auto (the default, which promotes to Nerd Font only on a positive signal), an explicit Nerd Font rung, a universal Unicode fallback, or off for decorative glyphs.
ui/list
Package list wraps bubbles/list with a task-pilot-style delegate: a thick left-border selection accent, title+description rows, and built-in filtering.
 Package list wraps bubbles/list with a task-pilot-style delegate: a thick left-border selection accent, title+description rows, and built-in filtering.
ui/logo
Package logo renders the OPENFGA block wordmark, in the spirit of charmbracelet/crush's stylized title.
 Package logo renders the OPENFGA block wordmark, in the spirit of charmbracelet/crush's stylized title.
ui/shell
Package shell renders the Crush-style playground frame: a left sidebar (gradient logo + context + nav + status footer), a main content pane, and a bottom status bar, composited flat on a lipgloss canvas with no painted panel backgrounds — structure comes from headers and rules.
 Package shell renders the Crush-style playground frame: a left sidebar (gradient logo + context + nav + status footer), a main content pane, and a bottom status bar, composited flat on a lipgloss canvas with no painted panel backgrounds — structure comes from headers and rules.
ui/toast
Package toast renders transient bottom-right status chips that auto-expire.
 Package toast renders transient bottom-right status chips that auto-expire.
version
Package version holds build information, injected at release time via -ldflags.
 Package version holds build information, injected at release time via -ldflags.
tools
docgen command
Command docgen generates the per-command MDX reference pages for the docs site (docs/site/src/content/docs/reference) from the live cobra tree, so the published reference can never drift from the binary.
 Command docgen generates the per-command MDX reference pages for the docs site (docs/site/src/content/docs/reference) from the live cobra tree, so the published reference can never drift from the binary.
genassets command
Command genassets generates the shell completions and man pages that ship inside the release archives and OS packages.
 Command genassets generates the shell completions and man pages that ship inside the release archives and OS packages.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.