GBOS CLI

Command-line interface for the Generative Business Operating System (GBOS) - a task management platform that connects AI coding agents to development workflows.

Installation

npm install -g gbos

Quick Start

# 1. Authenticate with GBOS
gbos auth

# 2. Connect to a development node (automatic after auth)
gbos connect

# 3. Start working on tasks
gbos continue

Commands

Authentication & Connection

Command	Description
gbos auth	Authenticate with GBOS (opens browser for OAuth)
gbos auth --force	Force re-authentication
gbos connect	Connect to a development node
gbos disconnect	Disconnect from the current node
gbos logout	Log out and clear credentials
gbos status	Show current authentication and connection status

Task Management

Command	Description
gbos tasks	List all tasks assigned to this node
gbos next	Preview the next task in the queue
gbos continue	Get the next task and output prompt for coding agent
gbos fallback	Cancel current task and revert changes
gbos add_task	Create a new task interactively

Help

Command	Description
gbos -h	Show help and all available commands
gbos <command> -h	Show help for a specific command

How It Works

1. Authentication Flow

gbos auth
    │
    ├─→ Opens browser for GBOS OAuth
    ├─→ Saves session to ~/.gbos/session.json
    ├─→ Registers MCP server for coding tools
    └─→ Automatically proceeds to connect

2. Task Workflow

gbos continue
    │
    ├─→ Checks for in-progress task (GET /cli/tasks/current)
    ├─→ If none, fetches next task with auto-assign (GET /cli/tasks/next?auto_assign=true)
    ├─→ Marks task as in_progress (POST /cli/tasks/:id/start)
    └─→ Outputs task prompt for coding agent

3. Working with Coding Agents

After connecting, run your favorite coding agent in the same terminal:

# Claude Code
claude

# Gemini CLI
gemini

# OpenAI Codex
codex

Then simply ask the agent to work on GBOS tasks:

• "Fetch and work on the next task from GBOS"
• "Run gbos continue and complete the task"
• "Check gbos tasks and work on the highest priority one"

Supported Coding Agents

GBOS CLI automatically configures MCP servers for:

• Claude Code - ~/.claude/settings.json
• Claude Desktop - ~/Library/Application Support/Claude/claude_desktop_config.json
• Gemini CLI - ~/.gemini/settings.json
• Codex CLI - ~/.codex/config.json
• Cursor IDE - ~/.cursor/mcp.json
• VS Code - ~/.vscode/mcp.json
• AntiGravity IDE - ~/.antigravity/mcp.json

Project Integration

When you run gbos connect in a project directory, it creates:

Skill Files

File	Purpose
CLAUDE.md	Instructions for Claude Code
.cursorrules	Instructions for Cursor IDE
GEMINI.md	Instructions for Gemini CLI
AGENTS.md	Instructions for other agents
.claude/skills/gbos/SKILL.md	Claude Code /gbos slash command

VS Code Tasks

.vscode/tasks.json with quick-access tasks:

• GBOS: Status
• GBOS: Tasks
• GBOS: Continue
• GBOS: Fallback

Configuration

Session File

Stored at ~/.gbos/session.json:

{
  "access_token": "gbos_...",
  "refresh_token": "gbos_refresh_...",
  "user_id": 1,
  "user_name": "John Doe",
  "account_id": 2,
  "account_name": "My Account",
  "connection": {
    "node": { "id": 72, "name": "my-node" },
    "application": { "id": 48, "name": "My App" }
  }
}

Environment Variables

Variable	Description
DEBUG=1	Enable debug output
GBOS_API_URL	Override API endpoint (default: https://api.gbos.io/api/v1)

API Endpoints

The CLI communicates with the GBOS API:

Endpoint	Method	Description
/cli/auth/init	POST	Initialize device auth flow
/cli/auth/status/:code	GET	Check auth status
/cli/applications	GET	List available applications
/cli/nodes	GET	List available nodes
/cli/connect/:nodeId	POST	Connect to a node
/cli/tasks	GET	List tasks for node
/cli/tasks	POST	Create a task
/cli/tasks/current	GET	Get in-progress task
/cli/tasks/next	GET	Get next task (supports ?auto_assign=true)
/cli/tasks/:id/start	POST	Start a task
/cli/tasks/:id/complete	POST	Complete a task
/cli/tasks/:id/fail	POST	Fail a task
/cli/tasks/:id/cancel	POST	Cancel a task

MCP Server

GBOS provides an MCP (Model Context Protocol) server that coding agents can use directly:

https://gbos-mcp-server-579767694933.us-south1.run.app/mcp

This is automatically configured when you run gbos auth.

Examples

Basic Workflow

# Install
npm install -g gbos

# Authenticate and connect
gbos auth

# Check status
gbos status

# See available tasks
gbos tasks

# Start working on next task
gbos continue

# If task fails or needs to be cancelled
gbos fallback

Create a Task

gbos add_task
# Follow interactive prompts:
# - Title
# - Description
# - Priority (low/medium/high/critical)
# - Task type (feature/bug/refactor/test/docs)
# - Prompt for agent
# - Attachments
# - Due date

Debug Mode

DEBUG=1 gbos connect
DEBUG=1 gbos tasks

Troubleshooting

Token Expired

gbos auth --force

Not Connected

gbos connect

Tasks Not Showing

Tasks may need to be assigned to your node. Use gbos next which auto-assigns pending tasks, or assign from the GBOS dashboard.

MCP Server Not Working

Re-run authentication to re-register MCP servers:

gbos auth --force

Links

• GBOS Platform: https://gbos.io
• API Documentation: https://api.gbos.io/docs
• Issues: https://github.com/mystroanalytics/gbos-cli/issues

License

MIT