Tiny framework for building self-documenting, LLM-friendly npm packages
npm install @juleswhite/promptable> Tiny framework for building self-documenting, LLM-friendly npm packages


A promptable package is an npm package designed for seamless interaction with Large Language Models (LLMs). It provides self-documenting CLI commands via npx that output structured, context-sized documentation optimized for LLM consumption.
Key Features:
- ✅ Self-documenting via npx executable
- ✅ Output sized for LLM context windows (≤2000 lines per command)
- ✅ Progressive navigation with next-step suggestions
- ✅ Universal --llm flag for LLM discoverability
- ✅ Zero dependencies, ~200 lines of code
``bash`
npm install @juleswhite/promptable
`javascript
#!/usr/bin/env node
import { createPromptable, printHeader } from '@juleswhite/promptable';
const cli = createPromptable({
title: 'My Package',
subtitle: 'A great package',
docsDir: './docs',
packageCommand: 'npx my-package'
});
// Add --llm command (required for promptable standard)
cli.addCommand('--llm', (cli) => {
printHeader(cli.config.title, cli.config.subtitle);
console.log('Welcome to my package!\n');
cli.printCommandList();
}, {
description: 'Getting started (default)',
aliases: ['--start']
});
// Add help command
cli.addCommand('--help', cli.createHelpCommand(), {
description: 'Show all commands',
aliases: ['-h']
});
// Add markdown-based documentation command
cli.addCommand('--guide',
cli.createMarkdownCommand('GUIDE.md', 'Getting Started'),
{ description: 'Usage guide' }
);
cli.run();
`
`json`
{
"name": "my-package",
"type": "module",
"bin": "./bin/cli.js",
"files": ["bin", "docs"],
"dependencies": {
"@juleswhite/promptable": "^1.0.0"
}
}
Important: Use the string form "bin": "./bin/cli.js" to automatically create a binary matching your package name. This ensures npx my-package --llm works correctly.
`bash`
chmod +x bin/cli.js
npm link
npx my-package --llm
StandardAll promptable packages MUST respond to the --llm flag:
`bash`
npx your-package --llm
This convention allows LLMs to automatically discover and navigate your package's documentation.
Creates a new PromptableCLI instance.
Config:
- title: string - Main title for headerssubtitle: string
- - Subtitle for headersdocsDir: string
- - Path to markdown documentationpackageCommand: string
- - Base command for navigation (e.g., "npx my-package")
#### .addCommand(name, handler, options)
Add a new command to the CLI.
- name: string - Command name (e.g., '--colors')handler: Function
- - Command handler (cli) => {}options.description: string
- - Command descriptionoptions.aliases: string[]
- - Array of command aliases
#### .run(args?)
Execute the CLI. Defaults to process.argv.slice(2).
#### .printCommandList()
Print all available commands with descriptions.
#### printHeader(title, subtitle?)
Print a colored header with separator lines.
#### printSection(title, content?)
Print a section with colored title and separator.
#### printNextStep(message, command)
Print a next-step suggestion with highlighted command.
#### colorize(text, color)
Colorize text with ANSI codes.
Available colors: cyan, blue, green, yellow, magenta, red, gray, bright, dim
#### readMarkdown(docsDir, filename)
Read a markdown file from the docs directory.
#### extractSection(content, sectionTitle)
Extract a section from markdown content by heading title.
#### .createHelpCommand()
Creates a standard help command that lists all available commands.
#### .createMarkdownCommand(filename, sectionTitle, nextStep?)
Creates a command that extracts and displays a markdown section.
Parameters:
- filename: string - Markdown file namesectionTitle: string
- - Section heading to extractnextStep?: { message: string, command: string }
- - Next step suggestion
#### .createFullDocCommand(filename)
Creates a command that outputs an entire markdown file.
`javascript
#!/usr/bin/env node
import { fileURLToPath } from 'url';
import { dirname, join } from 'path';
import {
createPromptable,
printHeader,
printSection,
colorize
} from '@juleswhite/promptable';
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
const docsDir = join(__dirname, '..', 'docs');
const cli = createPromptable({
title: '🎨 My Design System',
subtitle: 'Beautiful, accessible components',
docsDir,
packageCommand: 'npx my-design-system'
});
// Required: --llm entry point
cli.addCommand('--llm', (cli) => {
printHeader(cli.config.title, cli.config.subtitle);
printSection('🚀 Quick Start',
${colorize('1.', 'yellow')} Install: ${colorize('npm install my-design-system', 'bright')}
${colorize('2.', 'yellow')} Import: ${colorize('import { Button } from "my-design-system"', 'bright')}
${colorize('3.', 'yellow')} Use: ${colorize('', 'bright')}
);
cli.printCommandList();
}, {
description: 'Getting started guide (default)',
aliases: ['--start', '--get-started']
});
// Help command
cli.addCommand('--help', cli.createHelpCommand(), {
aliases: ['-h']
});
// Documentation from markdown
cli.addCommand('--colors',
cli.createMarkdownCommand('GUIDE.md', 'Color System', {
message: 'Learn about components:',
command: 'npx my-design-system --components'
}),
{ description: 'Color palette and usage' }
);
cli.addCommand('--components',
cli.createMarkdownCommand('GUIDE.md', 'Components'),
{ description: 'Available components' }
);
// Full docs
cli.addCommand('--full',
cli.createFullDocCommand('GUIDE.md'),
{ description: 'Complete documentation (large)' }
);
cli.run();
`
Traditional documentation has issues for LLM-assisted development:
1. Too Large - Full docs exceed LLM context windows
2. Poor Navigation - No clear path from A → B → C
3. Not Queryable - Can't ask "just show me X"
4. Static - Doesn't adapt to user's learning path
Promptable packages solve this by:
1. Chunking intelligently - Each command outputs a focused topic
2. Guiding navigation - Each output suggests the next logical step
3. Being queryable - npx package --topic gets exactly what you need
4. Adapting - Users choose their own path through the knowledge
5. Being paste-friendly - Clean output perfect for LLM prompts
Explore the full specification and examples:
`bash``
npx @juleswhite/promptable --llm # Getting started
npx @juleswhite/promptable --standard # The --llm flag convention
npx @juleswhite/promptable --patterns # Integration patterns
npx @juleswhite/promptable --api # API reference
npx @juleswhite/promptable --example # Complete example
npx @juleswhite/promptable --full # Full specification
- @majkapp/plugin-ui - UI component library with aesthetic documentation
Issues and PRs welcome! Please ensure your package follows the promptable package standard.
MIT © Jules White