Agentic Fabriq CLI Reference

Installation

pip install agentic-fabriq-sdkcopy

After installation, the afctl command will be available in your terminal.

Global Options

These options can be used with any command:

Global Commands

afctl version

Show version information.

afctl versioncopy

afctl status

Show system status and configuration.

afctl statuscopy

Output: A table showing gateway connection status, authentication status, and configuration file location.

afctl init

Initialize CLI configuration.

afctl init [OPTIONS]copy

Example:

afctl init --gateway-url https://dashboard.agenticfabriq.comcopy

Authentication Commands (afctl auth)

afctl auth login

Login to Agentic Fabriq using OAuth2/PKCE flow. Opens your default browser for authentication with Keycloak. Tokens are securely stored locally.

afctl auth login [OPTIONS]copy

Examples:

# Individual user login
afctl auth login

# Team organization login
afctl auth login --org freebies.com

# Login with saved organization
afctl config set organization_url freebies.com
afctl auth login

# Device code flow (headless/remote machines — no browser needed)
afctl auth login --remote

# Combine: remote + org
afctl auth login --remote --org freebies.comcopy

afctl auth logout

Logout from Agentic Fabriq. Revokes tokens and clears local authentication state.

afctl auth logout [OPTIONS]copy

afctl auth status

Show authentication status and token information.

afctl auth statuscopy

Output: A table showing authentication status (authenticated/expired), name, email, user ID, tenant ID, organization ID, token expiration time, refresh token availability, and gateway URL.

afctl auth refresh

Refresh authentication token. Uses the refresh token to obtain a new access token without requiring interactive login.

afctl auth refresh [OPTIONS]copy

afctl auth token

Display the current access token.

afctl auth token [OPTIONS]copy

Examples:

# Show truncated token
afctl auth token

# Show full token
afctl auth token --fullcopy

afctl auth whoami

Display information about the currently authenticated user.

afctl auth whoamicopy

Output: A table showing name, email, user ID, and tenant.

MCP Broker (afctl broker)

Run a local MCP broker that connects coding agents (Claude Code, Cursor, Codex) to Agentic Fabriq. This command is typically not run manually — it is spawned automatically by the coding agent based on your MCP config.

afctl broker [OPTIONS]copy

How it works:

• Communicates via stdio (JSON-RPC 2.0) with the coding agent
• Proxies MCP requests (list_tools, call_tool) to the Agentic Fabriq gateway via WebSocket
• Sends heartbeats every 60 seconds to keep the session alive
• Session auto-expires ~3 minutes after the broker process exits
• Transparently re-establishes session if the auth token expires

MCP config example (place in ~/.claude/mcp.json or ~/.cursor/mcp.json):

{
  "mcpServers": {
    "agentic-fabriq": {
      "command": "afctl",
      "args": ["broker"]
    }
  }
}copy

VM Management (afctl vm)

Manage local virtual machines for computer-use coding agents.

afctl vm serve

Start the local VM management server. Provides a REST API for creating, starting, stopping, and deleting QEMU-based VMs. Automatically connects to the Agentic Fabriq dashboard via WebSocket relay if authenticated.

afctl vm serve [OPTIONS]copy

Examples:

# Start with default port
afctl vm serve

# Start on custom port
afctl vm serve --port 8080copy

Configuration Commands (afctl config)

afctl config show

Show current configuration.

afctl config show [OPTIONS]copy

afctl config set

Set a configuration value.

afctl config set KEY VALUEcopy

Settable keys:

• gateway_url - Gateway URL
• keycloak_url - Keycloak URL
• output_format - Default output format (table, json, yaml)
• page_size - Default page size for list commands

Note: tenant_id cannot be set manually—it comes from authentication.

Examples:

afctl config set gateway_url https://dashboard.agenticfabriq.com
afctl config set output_format json
afctl config set page_size 50copy

afctl config get

Get a configuration value.

afctl config get KEYcopy

Readable keys:

• gateway_url, keycloak_url, keycloak_realm, keycloak_client_id
• tenant_id, output_format, page_size, config_file
• verbose, authenticated

Example:

afctl config get gateway_urlcopy

afctl config reset

Reset configuration to defaults.

afctl config reset [OPTIONS]copy

Tool Commands (afctl tools)

afctl tools list

List your tool connections (configured and connected tools).

afctl tools list [OPTIONS]copy

Examples:

# List all connections
afctl tools list

# Paginate results
afctl tools list --page 2 --page-size 10

# Search by tool type
afctl tools list --search gmail
afctl tools list --search google

# Filter by tool type
afctl tools list --tool slack

# Combined search and filtering
afctl tools list --tool google --search gmailcopy

afctl tools get

Get tool connection details.

afctl tools get CONNECTION_ID [OPTIONS]copy

Example:

afctl tools get my-gmailcopy

afctl tools add

Add a new tool connection with credentials.

afctl tools add TOOL [OPTIONS]copy

Methods:

• oauth3 - Uses platform OAuth (recommended for Google, Slack, Notion, GitHub)
• api_credentials - Uses your own credentials (token or client ID/secret)

Examples:

# Platform OAuth (no credentials needed)
afctl tools add google_drive --connection-id google-work --method oauth3
afctl tools add slack --connection-id slack-work --method oauth3
afctl tools add notion --connection-id notion-work --method oauth3
afctl tools add github --connection-id github-work --method oauth3

# API token (Notion integration token, Slack bot token)
afctl tools add notion --connection-id notion-work --method api_credentials \
  --token "secret_abc123"

# Your own OAuth app
afctl tools add google_drive --connection-id google-work --method api_credentials \
  --client-id "123.apps.googleusercontent.com" \
  --client-secret "GOCSPX-abc123"copy

Supported Google tools: google_drive, google_docs, google_sheets, google_slides, gmail, google_calendar, google_meet, google_forms, google_classroom, google_people, google_chat, google_tasks

afctl tools connect

Complete OAuth connection (opens browser for authorization).

afctl tools connect CONNECTION_ID [OPTIONS]copy

Example:

afctl tools connect my-gmailcopy

afctl tools disconnect

Disconnect a tool (remove credentials but keep connection entry).

afctl tools disconnect CONNECTION_ID [OPTIONS]copy

Example:

afctl tools disconnect my-gmail
afctl tools disconnect my-gmail --forcecopy

afctl tools remove

Remove a tool connection completely (delete entry and credentials).

afctl tools remove CONNECTION_ID [OPTIONS]copy

Example:

afctl tools remove my-gmail
afctl tools remove my-gmail --forcecopy

Application Commands (afctl applications)

afctl applications register

Step 1: Register a new application (returns activation token).

afctl applications register [OPTIONS]copy

Example:

afctl applications register \
  --app-id my-slack-bot \
  --scopes slack:channels:read,slack:chat:write,google:gmail.send \
  --display-name "My Slack Bot"copy

Output: Returns an activation token (valid for 1 hour, single use).

afctl applications activate

Step 2: Activate an application (saves credentials locally).

afctl applications activate [OPTIONS]copy

Examples:

# Basic activation
afctl applications activate --app-id my-slack-bot --token <activation-token>

# With IdP credentials (for SSO organizations)
afctl applications activate --app-id my-bot --token <token> \
  --idp-client-id 0oa... --idp-client-secret <secret>copy

Output: Saves credentials to ~/.af/applications/{app_id}.json

afctl applications list

List all registered applications.

afctl applications list [OPTIONS]copy

Example:

afctl applications list
afctl applications list --format jsoncopy

afctl applications show

Show details of a registered application.

afctl applications show APP_ID [OPTIONS]copy

Examples:

afctl applications show my-slack-bot
afctl applications show my-slack-bot --reveal-secretcopy

afctl applications delete

Delete a registered application. Deletes the server registration, removes local credentials, and invalidates all active tokens.

afctl applications delete APP_ID [OPTIONS]copy

Examples:

afctl applications delete my-slack-bot
afctl applications delete my-slack-bot --yescopy

afctl applications test

Test application authentication. Attempts to exchange credentials for a token to verify the application is properly registered.

afctl applications test APP_IDcopy

Example:

afctl applications test my-slack-botcopy

Configuration File

The CLI stores configuration at ~/.af/config.json:

{
  "gateway_url": "https://dashboard.agenticfabriq.com",
  "keycloak_url": "https://auth.agenticfabriq.com",
  "tenant_id": "uuid-...",
  "output_format": "table",
  "page_size": 20
}copy

Application credentials are stored in ~/.af/applications/{app_id}.json.

Environment Variables

The following environment variables can override configuration:

Common Workflows

Individual User Setup

# Initialize and login
afctl init
afctl auth login

# Check status
afctl status
afctl auth whoamicopy

Team Organization Setup

# Login to organization
afctl auth login --org mycompany.com

# Or save organization in config
afctl config set organization_url mycompany.com
afctl auth logincopy

Adding a Tool Connection

# Add connection with platform OAuth
afctl tools add gmail --connection-id my-gmail --method oauth3

# Complete OAuth
afctl tools connect my-gmail

# Verify
afctl tools get my-gmailcopy

Registering an Application

# Step 1: Register
afctl applications register \
  --app-id my-agent \
  --scopes slack:chat:write,google:gmail.send

# Step 2: Activate (use the token from step 1)
afctl applications activate --app-id my-agent --token <token>

# Test authentication
afctl applications test my-agentcopy