@kolaborate/kola-cli

v0.5.2

Published

15 days ago

Agent-first CLI for the Kolaborate ecosystem (proprietary — Kolaborate Platforms Ltd)

Downloads

465

0High
0Medium
0Low

kolaborateplatforms

Kola CLI

The agent-first CLI for the Kolaborate ecosystem — full programmatic access to the marketplace, academy, admin operations, analytics, and testing platform.

Features

RBAC-first — every command is protected by Role-Based Access Control with scoped API keys
Audit-logged — every mutation (create, update, publish, etc.) is logged for non-repudiation
MCP native — exposes all commands as MCP tools for seamless AI agent integration
Dual-actor — supports human (Firebase JWT) and agent (KOLA_API_KEY) authentication in the same CLI
Dry-run everywhere — pass --dry-run to preview any mutation before it runs
JSON output — pass --json to any command for machine-readable output
Multi-format export — analytics, jobs, kolaborators, and academy data export as table, JSON, or CSV
Staging-aware — yellow [STAGING] banner appears when KOLA_CONVEX_URL points to a non-default deployment

Installation

# Global install (recommended)
npm install -g @kolaborate/kola-cli

# One-off with npx
npx @kolaborate/kola-cli --help

Pre-built binaries for macOS (arm64/x64) and Linux (x64) are available on the GitHub Releases page.

Quick Start

kola auth login          # sign in with your Kolaborate account
kola jobs list           # browse marketplace jobs
kola academy list        # browse academy courses
kola testing runs list   # view test runs
kola admin analytics overview --range 30d   # admin only

Authentication

Human users

kola auth login
kola auth status        # check current session
kola auth whoami        # show resolved identity + roles
kola auth logout        # clear local credentials

Saves a Firebase token to ~/.kola/credentials.json. Token refresh is automatic.

Agents / CI

kola auth apikey create --name "ci-agent" --scopes "jobs:read,chats:read"
kola auth apikey list
kola auth apikey revoke <keyId>

Pass the key as KOLA_API_KEY. No browser needed. Agents are blocked from admin-level mutations by the security gate.

MCP Setup

Hosted (recommended)

{
  "mcpServers": {
    "kolaborate": {
      "url": "https://mcp.kolaborate.com/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_KOLA_API_KEY" }
    }
  }
}

Local stdio (development)

{
  "mcpServers": {
    "kolaborate": {
      "command": "kola",
      "args": ["serve", "mcp"],
      "env": { "KOLA_API_KEY": "your_agent_api_key" }
    }
  }
}

Command Reference

User-facing commands

| Command | Description | |---|---| | kola auth | Login, logout, status, whoami, manage API keys | | kola config | View and set local CLI configuration | | kola jobs | Browse, create, and manage marketplace job postings | | kola kolaborators | Search and manage kolaborator profiles | | kola chats | Send and read direct messages and channel conversations | | kola profile | Manage your user identity, avatar, and public profile | | kola quotations | Create and track project quotations and proposals | | kola careers | Browse open positions and submit career applications | | kola notifications | List and mark notifications as read | | kola support | Open and view support tickets | | kola serve | Start a platform adapter (WhatsApp, Discord, Telegram) or MCP server |

Academy (user + instructor)

| Command | Description | |---|---| | kola academy list | Browse published courses | | kola academy get <id> | Get full course details | | kola academy enroll <id> | Enroll in a course | | kola academy generate outline <topic> | AI-generate a course outline | | kola academy course create | Create a new interactive course (draft) | | kola academy course bootstrap <manifest> | Full course creation workflow — sources, videos, outputs, publish | | kola academy course publish --course <id> | Publish a course | | kola academy course source | Manage knowledge sources for a course | | kola academy course video | Manage story videos for a course | | kola academy course output | Generate AI outputs (summary, study guide, flashcards, quiz, FAQ) |

One-shot course bootstrap

kola academy course bootstrap runs the entire course creation workflow idempotently — creates the course, uploads sources, waits for AI processing, uploads story videos, publishes, and generates outputs. Writes a checkpoint so --resume picks up after a failed run.

kola academy course bootstrap ./manifest.json
kola academy course bootstrap ./manifest.json --resume
kola --dry-run academy course bootstrap ./manifest.json   # preview only

Manifest shape:

{
  "course": {
    "title": "AI at Work",
    "description": "@./description.md",
    "level": "beginner",
    "tags": ["ai", "productivity"],
    "dailyChatLimit": 50
  },
  "sources": [{ "title": "Module 1", "content": "@./01.md" }],
  "storyVideos": [{ "title": "Intro", "file": "@./intro.mp4" }],
  "banner": { "file": "@./banner.png" },
  "outputs": ["summary", "study_guide", "flashcards", "quiz", "faq"],
  "publish": true
}

The @ prefix reads content from a path relative to the manifest file.

Testing & QA

kola testing
├── projects     list / get / create / update / delete
├── cases        list / get / create / update / delete / bulk-assign
├── runs         list / get / create / start / complete / submit
├── templates    list / get / create / update / delete
├── results      list / get / update (pass/fail/skip/block)
├── bugs         list / get / create / update / close
├── retests      list / get / create / resolve
├── assignments  list / get / create / update
├── sessions     list / get / create / close
├── analytics    project / tester / export
├── export       json / csv
├── payment      config get / set
├── notifications list / mark-read
└── agent        bulk-run / batch-assign / sync-results

Platform adapters & MCP server (`kola serve`)

kola serve
├── whatsapp [--daemon]   Start WhatsApp adapter (foreground or daemon)
├── discord  [--daemon]   Start Discord bot adapter
├── telegram [--daemon]   Start Telegram bot adapter
├── mcp                   Start the MCP stdio server (for AI agents)
└── all                   Start every configured adapter

Admin (requires admin credentials)

All kola admin commands require Firebase login with adminRole set in the Kolaborate backend. Agents are blocked at the security gate, and a yellow [STAGING] banner is printed if KOLA_CONVEX_URL is set.

kola admin
├── tasks        Daily task management
├── leave        Leave request management
├── audit        Security audit log viewer
├── approvals    Approval queue management (list / approve)
├── requisitions 4-step workflow (prepare → authorize → verify → receive)
├── employees    Employee profile management
├── jobs         Job admin and reconciliation
├── orders       Order tracking management
├── attendance   Attendance management
├── reports      Report generation and scheduling
├── users        User management
├── kolaborators Kolaborator search and profiles
├── support      Bulk support operations
├── academy      Full academy admin (see below)
└── analytics    Platform & impact analytics (see below)

`kola admin analytics`

Platform-wide and impact analytics with table / JSON / CSV output.

kola admin analytics
├── overview        Platform-wide snapshot (users, jobs, enrollments, engagement)
├── impact          Impact metrics (gigs, workers, revenue, training)
│   --month <YYYY-MM>   Specific month
│   --from / --to       Date range
│   --lifetime          Aggregate lifetime totals
├── impact-months   List months that have impact data
├── revenue         Revenue analytics over time
├── engagement      User engagement and activity metrics
└── agents          AI agent analytics
    ├── list        List all AI agents with usage stats
    └── get <id>    Full details for an AI agent

Every command supports --format <table|json|csv> and --output <path> for writing to a file.

kola admin analytics overview --range 30d --format csv --output overview.csv
kola admin analytics impact --month 2026-04 --format json
kola admin analytics impact --lifetime
kola admin analytics agents list --format json

`kola admin academy`

Complete CLI parity with the Academy admin web panel. Requires academyRole: instructor | admin.

kola admin academy
├── courses
│   ├── list / get / publish / unpublish / delete / duplicate / analytics / enrollments
│   ├── modules  list / create / update / delete
│   └── lessons  list / create / update
│
├── hackathons
│   ├── list / get / create / update / delete / status / duplicate
│   ├── participants / submissions / submission
│   ├── grade <registrationId>     Grade with rubric, score, review, headline
│   ├── rubric   show / set
│   ├── results  show / publish
│   ├── report   manage post-event report
│   ├── ideas    list / generate
│   └── qa       list / answer
│
├── internships
│   ├── list / get / create / update / publish / close
│   ├── applications  list / update
│   ├── sessions      list / create / update / delete
│   ├── activities    list / create
│   └── students      list
│
├── waitlist
│   └── list / approve / reject / stats
│
└── stats
    ├── dashboard / hackathons
    └── homepage  list / update <key>

Create a hackathon from a spec file:

kola admin academy hackathons create --spec @./hackathon.json
kola admin academy hackathons create --spec '{"title":"My Hack","slug":"my-hack",...}'

Update banner, prize, currency, or status:

kola admin academy hackathons update <id> --banner <url> --prize 250 --currency KLC
kola admin academy hackathons update <id> --status active

Grade a hackathon submission:

kola admin academy hackathons grade <registrationId> \
  --score 87 \
  --rubric @./scores.json \
  --review "Strong execution, novel approach" \
  --winner

Manage the waitlist:

kola admin academy waitlist list --status pending
kola admin academy waitlist approve <entry-id>
kola admin academy waitlist reject <entry-id> --notes "Not eligible"

Global Flags

| Flag | Description | |---|---| | --json | Machine-readable JSON output (all commands) | | --dry-run | Preview mutations without writing to the database | | --quiet | Suppress non-error output (useful in CI) |

Environment Variables

| Variable | Description | |---|---| | KOLA_API_KEY | Agent API key for headless / CI authentication | | KOLA_CONVEX_URL | Override the Convex deployment (triggers [STAGING] banner) | | KOLA_CLOUDINARY_CLOUD_NAME | Cloudinary cloud name for video/image uploads | | KOLA_CLOUDINARY_UPLOAD_PRESET | Cloudinary unsigned upload preset | | KOLA_CLOUDINARY_UPLOAD_FOLDER | Upload destination folder |

All other configuration (Convex URL, Firebase project) is pre-configured. Human users authenticate via kola auth login — no environment variables needed.

License & Intellectual Property

This package is proprietary software of Kolaborate Platforms Ltd. It is published to npm purely as a delivery channel — making npm install -g @kolaborate/kola-cli work for authorized users — not as an open-source release. Use is governed by the terms in the LICENSE file and any separate written agreement you may have with Kolaborate.

You may install and run the CLI to access Kolaborate services with valid credentials. You may not redistribute, fork, modify, reverse-engineer, or use this software to build a competing product. See LICENSE for full terms. Licensing inquiries: [email protected].