ManaBase CLI

CLI for the ManaBase Backend-as-a-Service platform.

Sync API contracts to frontend projects, authenticate with the ManaBase API, and manage your ManaBase resources from the terminal.

Install

npm install -g manabase

# Verify installation
manabase --help

Quick Start

# 1. Create your frontend project
mkdir my-lms-frontend && cd my-lms-frontend

# 2. Pull ManaBase contracts
manabase init --repo [email protected]:manaable/manabase-mvp.git

# 3. Start building — point your AI agent to:
#    ./manabase/FRONTEND_AGENT.md

Authentication

ManaBase CLI supports authenticated access to the ManaBase API.

# Log in to a ManaBase instance
manabase login

# Check who you're logged in as
manabase whoami

# Log out
manabase logout

The login command prompts for your ManaBase API URL, tenant name (slug), email, and password. Credentials are stored in ~/.manabase/credentials.json with restricted file permissions.

Multiple profiles are supported for working with different tenants.

API Commands

Query ManaBase resources directly from the terminal (requires login):

# Your profile
manabase me

# Courses
manabase courses list
manabase courses get <course-id>

# Users
manabase users list
manabase users get <user-id>

# Analytics
manabase analytics dashboard

MCP Server (AI Agent Integration)

ManaBase CLI includes a built-in MCP server that exposes the ManaBase API as tools for AI agents like Claude Code, Cursor, and other MCP-compatible clients.

# Start the MCP server (stdio transport)
manabase mcp

Setup for Claude Code

Add to your project's .mcp.json or Claude Code settings:

{
  "mcpServers": {
    "manabase": {
      "command": "manabase",
      "args": ["mcp"]
    }
  }
}

The MCP server shares the same credentials as the CLI — run manabase login first, then AI agents can automatically discover and call tools like list_courses, get_user, get_analytics_dashboard, etc.

Available MCP Tools

| Tool | Description | |------|-------------| | auth_status | Check login status and current profile | | get_me | Get current user profile | | list_courses | List all courses | | get_course | Get course details by ID | | list_users | List all users | | get_user | Get user details by ID | | get_user_by_email | Look up user by email | | get_analytics_dashboard | Overview stats | | get_course_analytics | Course-specific analytics | | list_enrollments | List enrollments for a course | | list_organizations | List all organizations | | resolve_tenant | Resolve tenant slug to UUID | | list_audit_logs | Recent audit log entries |

manabase init

Initialize ManaBase contracts in your frontend project.

manabase init --repo [email protected]:manaable/manabase-mvp.git
manabase init --repo [email protected]:manaable/manabase-mvp.git --dir ./contracts
manabase init --repo [email protected]:manaable/manabase-mvp.git --branch develop

Options:

| Option | Default | Description | |--------|---------|-------------| | --repo <url> | (required on first use) | ManaBase git repository URL | | --dir <path> | ./manabase | Directory to store contracts | | --branch <name> | main | Branch to pull from |

What it does:

1. Clones the ManaBase repository (shallow clone, minimal download)
2. Extracts the contracts/ folder into your project
3. Creates a .manabase.json lockfile tracking version and source

Output:

manabase-frontend/
├── .manabase.json          ← Lockfile (version, source, last updated)
└── manabase/               ← Contracts (all you need to build a frontend)
    ├── FRONTEND_AGENT.md   ← START HERE — AI agent instructions
    ├── CONTEXT.md           ← LMS domain knowledge, client archetypes
    ├── AGENTS.md            ← Detailed API reference guide
    ├── VERSION              ← Contract version (e.g., 0.9.0)
    ├── CHANGELOG.md         ← What changed between versions
    ├── api/                 ← Endpoint contracts (54 endpoints across 9 domains)
    ├── types/               ← Data model definitions (Zod schemas)
    ├── errors/              ← Error code catalog per domain
    ├── auth/                ← Auth flows, roles, JWT tokens
    └── events/              ← Realtime event schemas

manabase update

Update contracts to the latest version.

manabase update

What it does:

1. Reads .manabase.json to find current version and source
2. Fetches the latest contracts from the repository
3. Shows what changed (changelog diff between versions)
4. Replaces local contracts with the latest version
5. Updates the lockfile

Example output:

🔄 Checking for updates...

   Current version: 0.8.0
   Source:          [email protected]:manaable/manabase-mvp.git
   Last updated:    2026-03-17T10:00:00.000Z

   Fetching latest...
   ─── Changes since v0.8.0 ───
   ## [0.9.0]
   ### Added
   - Notifications domain: 8 endpoints
   ─────────────────────────────────

   Updating v0.8.0 → v0.9.0...
   ✓ Updated to v0.9.0

For AI Agents Building Frontends

After running manabase init, point your AI agent to these files in order:

1. ./manabase/FRONTEND_AGENT.md — Step-by-step bootstrap instructions. Tells the agent exactly what to do: understand the domain, ask about the client, choose a tech stack, read contracts, plan, then build.

2. ./manabase/CONTEXT.md — LMS domain knowledge and client archetypes (K-12, University, Corporate Training, Coaching, Non-profit). The agent uses this to ask the right questions before building.

3. ./manabase/AGENTS.md — Detailed API reference with response envelopes, error handling, and auth conventions.

The agent will:

• Ask who the client is and what archetype they match
• Recommend a tech stack (Next.js, Flutter, etc.)
• Read the relevant API contracts
• Build the frontend using contracts as the source of truth

No Supabase SDK or credentials needed. The frontend authenticates via ManaBase API endpoints using an API key (X-API-Key header).

How Authentication Works

Frontend                              ManaBase API
   │                                       │
   │── POST /api/v1/auth/login ───────────▶│
   │   X-API-Key: <your-org-api-key>      │
   │   { email, password }                 │
   │                                       │
   │◀── { token, refresh_token, user } ────│
   │                                       │
   │── GET /api/v1/courses ───────────────▶│
   │   X-API-Key: <your-org-api-key>      │
   │   Authorization: Bearer <token>       │
   │                                       │
   │◀── { data: [...courses] } ────────────│

The API key is provided when a tenant is set up in ManaBase. Each organization gets a unique API key.

Lockfile (.manabase.json)

{
  "version": "0.9.0",
  "source": "[email protected]:manaable/manabase-mvp.git",
  "branch": "main",
  "updatedAt": "2026-03-17T13:19:52.612Z",
  "dir": "./manabase"
}

Pin to a version by not running manabase update until you're ready. Review the CHANGELOG before updating to understand what changed.

Requirements

• Node.js >= 20 (check with node --version)
• Git (for cloning the ManaBase repo)
• SSH access to the ManaBase repository (your SSH key must be configured for the GitHub account that has access)

Troubleshooting

manabase: command not found

• Ensure Node.js >= 20 is active: node --version
• Reinstall using the install command above (do not use npm install -g git+ssh://...)

Directory already exists on init

• Contracts are already initialized. Use manabase update instead.

Permission denied during clone

• Your SSH key doesn't have access to the ManaBase repo
• Test with: ssh -T [email protected]

No .manabase.json found on update

• Run manabase init first to initialize contracts