margins

margins-cli

CLI for Margins — review layer for Markdown in Git.

Margins is a review platform where humans and AI agents are equal participants. It renders Markdown files from a Git repository in a clean UI where reviewers can open discussions, propose changes, and approve content. margins-cli exposes every Margins action as a shell command, making it usable in scripts, CI pipelines, and by AI agents.

Installation

margins-cli lives at github.com/alvistar/margins-cli.

Run without installing (recommended):

npx github:alvistar/margins-cli <command>

No token, no registry setup — works anywhere you have Node.js and Git installed, including CI pipelines and AI agent environments.

Install globally:

npm install -g github:alvistar/margins-cli

Or clone and build locally:

git clone https://github.com/alvistar/margins-cli.git
cd margins-cli
npm install && npm run build
npm link   # makes 'margins' available globally

Quick Start

# Log in via browser (one-time)
margins auth login

# See your workspaces
margins workspace list

# Push local markdown to a brand-new workspace (no GitHub repo needed)
margins workspace push --project my-docs --dir ./docs

# List open discussions in the current repo
margins discuss list

# Create a discussion on a file
margins discuss create --path docs/intro.md --body "This section needs a concrete example."

Authentication

Two methods are supported. The active credential is resolved in priority order:

Priority	Source	Set by
1	--api-key <key> flag	any command
2	MARGINS_API_KEY env var	shell / CI environment
3	Stored static API key	margins config set-key
4	Stored Keycloak access token	margins auth login

Browser login (recommended for humans)

margins auth login

Opens your browser to complete OAuth 2 PKCE against Keycloak. On success, the access token and refresh token are stored locally. The token is refreshed automatically before it expires — no re-login needed.

Static API key (recommended for CI / agents)

Mint a key from the Margins web UI or the API (POST /api/keys), then store it:

margins config set-key mrgn_...
# or per-invocation:
margins --api-key mrgn_... workspace list
# or via environment:
MARGINS_API_KEY=mrgn_... margins workspace list

Static keys support two scopes: comment (read + create discussions) and edit (full write access).

---

Commands

Global Flags

Available on every command.

Flag	Description
-v, --version	Print version and exit
--json	Output as JSON — for scripting and agents
--verbose	Enable debug logging
--no-color	Disable ANSI colors
--server-url <url>	Override the server URL (default: https://margins.app)
--api-key <key>	Override the API key for this invocation

---

config

Manage local CLI configuration.

config show

Display the active configuration.

margins config show
margins config show --json

Shows the active server URL, the masked API key or token, and whether auth came from auth login or config set-key.

config set-key <key>

Store a static Margins API key.

margins config set-key mrgn_abc123...

Saves the key to the global config file. Clears any previously stored Keycloak session.

config set-url <url>

Override the server URL (useful for self-hosted Margins instances).

margins config set-url https://margins.example.com

---

auth

Authentication commands.

auth login

Log in via browser using Keycloak OAuth 2 + PKCE.

margins auth login

Opens a browser window to complete the OAuth flow. On completion, stores the Keycloak access token and refresh token locally. Subsequent commands use the token automatically, refreshing it transparently when it expires.

Note: The Keycloak client must have http://localhost:* registered as a valid redirect URI. See TODOS.md for the Keycloak admin configuration step.

auth whoami

Show the currently authenticated identity.

margins auth whoami
margins auth whoami --json

Calls GET /api/auth/whoami and displays your user ID, email, and role.

auth logout

Revoke the stored session and clear local credentials.

margins auth logout

Revokes the Keycloak refresh token and clears the stored access/refresh tokens from the config file. The server URL is preserved.

---

workspace

Manage Margins workspaces. A workspace is the unit of review in Margins. There are two kinds: