Playbook Workshop TUI

Interactive CLI tool to browse and access Potentialis Day workshop prompts.

Features

• 🔍 Browse all prompts - View both listed and unlisted prompts
• 🎯 Search & filter - Quickly find prompts by typing to search
• ⌨️ Keyboard navigation - Navigate with arrow keys and Enter
• 🔗 Quick access - Get direct URLs to prompt pages
• 📱 QR codes - Generate QR codes in terminal for easy mobile access
• 💾 Download QR codes - Save QR codes as PNG files to current directory
• 🎨 Beautiful UI - Colorful terminal interface with visual indicators

Installation

Install globally from npm:

npm install -g @potentialis/playbookws

For Development

1. Clone the repository:

git clone [email protected]:YOUR_ORG/playbook-workshop-tui.git
cd playbook-workshop-tui

2. Install dependencies:

bun install

3. Build the project:

bun run build

4. Link locally for testing:

npm link

Usage

Simply run the command:

playbookws

Interactive Controls

1. Search: Start typing to filter prompts in real-time
2. Navigate: Use ↑ ↓ arrow keys to move through the list
3. Select: Press Enter to view a prompt's details
4. Download: Select "Download QR Code" to save QR code as PNG
5. Back: Select "Back to List" or press Enter on "Back to List" to return

Example Workflow

$ playbookws

🔍 Search: [type to filter]
10 prompts found

  Workflow Mapping Assistant
  AI Critical Thinking Partner
▶ Socrates AI Critical Thinking Partner
  Consequence Predictor
  ...

After selecting a prompt:

Socrates AI Critical Thinking Partner (Sharper Version)
Status: Listed

URL: https://workshop.potentialis.ai/03-socrates-ai-critical-thinking-partner-sharper-version

[QR CODE DISPLAYED IN TERMINAL]

Select an option:
▶ 💾 Download QR Code
  ← Back to List

Configuration

The base URL is configured in source/config.ts. To change the API endpoint:

export const BASE_URL = 'https://workshop.potentialis.ai';

After changing, rebuild the project:

bun run build

API Endpoint

The CLI connects to the /api/prompts endpoint which returns:

[
	{
		"slug": "prompt-slug",
		"title": "Prompt Title",
		"listed": true,
		"url": "https://workshop.potentialis.ai/prompt-slug"
	}
]

Development

Scripts

• bun run build - Compile TypeScript to JavaScript
• bun run dev - Watch mode for development
• bun run test - Run tests with formatting and linting

Project Structure

playbook-workshop-tui/
├── source/
│   ├── cli.tsx              # CLI entry point
│   ├── app.tsx              # Main application component
│   ├── api.ts               # API client
│   ├── config.ts            # Configuration (BASE_URL)
│   └── components/
│       ├── PromptList.tsx   # List view with search
│       └── PromptDetail.tsx # Detail view with QR code
├── dist/                    # Compiled JavaScript (gitignored)
├── package.json
└── tsconfig.json

Dependencies

• ink - Terminal UI framework
• ink-select-input - Interactive list selection
• ink-text-input - Search input component
• ink-spinner - Loading spinner
• qrcode - QR code generation (for PNG files)
• qrcode-terminal - QR code display in terminal
• cross-fetch - HTTP client
• meow - CLI argument parser
• React - UI library

Requirements

• Node.js 16 or higher
• Access to the API endpoint at https://workshop.potentialis.ai

Troubleshooting

Connection Error

If you see "Unable to connect to API", ensure:

1. The Next.js app is deployed and accessible
2. The /api/prompts endpoint is working
3. You have internet connectivity

Build Errors

If build fails:

rm -rf node_modules dist
bun install
bun run build

License

MIT