proletariat
Documentation Menu

Getting Started

Core Concepts

Features

CLI Reference

JSON Mode

Every interactive prompt in Proletariat has a JSON counterpart. When agents run the CLI, they receive structured JSON instead of interactive menus — enabling fully autonomous, machine-to-machine workflows.

How It Works

Proletariat commands detect when they're being run by an agent (via the --json flag or agent environment detection). Instead of rendering interactive menus, they output structured JSON that describes the prompt, its choices, and metadata.

Human mode (interactive)
$ prlt ticket list --column "Ready"
? Select a ticket: (Use arrow keys)
❯ TKT-001 - Implement rate limiting
  TKT-002 - Fix login redirect
  TKT-003 - Add dark mode
Agent mode (JSON)
$ prlt ticket list --column "Ready" --json
{
  "prompt": {
    "type": "list",
    "name": "ticket",
    "message": "Select a ticket:",
    "choices": [
      { "name": "TKT-001 - Implement rate limiting", "value": "TKT-001" },
      { "name": "TKT-002 - Fix login redirect", "value": "TKT-002" },
      { "name": "TKT-003 - Add dark mode", "value": "TKT-003" }
    ]
  },
  "metadata": {
    "command": "ticket:list",
    "column": "Ready"
  }
}

Enabling JSON Mode

MethodDescription
--json flagAdd --json to any command for structured output
--machine flagAlias for --json
Agent detectionAutomatically enabled when running inside an agent session
# Explicit JSON mode
$ prlt board view --json
$ prlt ticket show TKT-001 --json
$ prlt work status --json

Why JSON Mode Matters

JSON mode is what makes Proletariat truly autonomous. Without it, AI agents would need to parse colorized terminal output and interact with arrow-key menus. With JSON mode:

  • Agents read structured data — No screen-scraping or regex parsing
  • Orchestrators compose commands — Chain CLI calls in automation scripts
  • Custom tooling integrates cleanly — Build dashboards, bots, or pipelines on top

Prompt Config Schema

JSON mode prompt configs follow a consistent schema:

{
  "prompt": {
    "type": "list" | "input" | "checkbox",
    "name": "fieldName",
    "message": "Human-readable question",
    "choices": [
      { "name": "Display text", "value": "machine-value" }
    ]
  },
  "metadata": {
    "command": "command:name",
    ...additionalContext
  }
}

Tip

The prompt config mirrors the inquirer.js prompt format, so you can use the same logic to drive both human and agent interactions.