Common use cases
Each task in this document includes clear instructions, example commands, and best practices to help you get the most from BLACKBOX CLI.
Create new projects from scratch
Build a complete web application
Suppose you want to create a full-featured web application with modern technologies.
blackbox session
``` > create a todo list web app using React, TypeScript, and Tailwind CSS
``` > add user authentication and data persistence to the todo app
```
```
> implement drag-and-drop functionality for reordering tasks
```
```
> add dark mode toggle and responsive design
``` > configure the development server and build scripts
```Tips:
- Start with a clear description of what you want to build
- Ask for modern best practices and technologies
- Request proper project structure and organization
Generate API backends
Suppose you need to create a REST API for your application.
> create a Node.js Express API for a blog application with user management
``` > add PostgreSQL database integration with Prisma ORM
``` > add JWT authentication and authorization middleware
``` > create CRUD endpoints for posts, comments, and user profiles
```Tips:
- Specify the database and ORM you prefer
- Request proper error handling and validation
- Ask for API documentation generation
Debug and fix existing code
Suppose you've encountered errors in your application and need to identify and fix them quickly.
> my React app crashes when users try to submit the contact form
``` > analyze the contact form component and find the bug
``` > fix the form validation error and add proper error handling
``` > test the contact form to ensure it works correctly now
```Tips:
- Provide specific error messages when available
- Mention the steps to reproduce the issue
- Ask for explanations of why the bug occurred
Improve and optimize existing code
Suppose you need to enhance the performance and maintainability of your codebase.
> analyze my React components for performance issues
``` > optimize the user dashboard component to reduce re-renders
``` > refactor the authentication logic into reusable hooks
``` > update the state management to use React Query for server state
```Tips:
- Ask for specific performance metrics and improvements
- Request explanations of optimization techniques used
- Focus on one area at a time for manageable changes
Add new features to existing projects
Suppose you want to extend your application with additional functionality.
> review my e-commerce app structure and suggest where to add a wishlist feature
``` > add a wishlist feature with add/remove functionality and persistence
``` > update the product cards to include wishlist buttons
``` > create a wishlist page where users can view and manage saved items
```Tips:
- Consider how new features integrate with existing code
- Ask for consistent styling and user experience
- Request proper testing for new functionality
Set up development environments
Suppose you need to configure a complete development environment for your project.
> set up Webpack configuration for my React TypeScript project
``` > configure hot reloading and development server with proxy settings
``` > configure Jest and React Testing Library for unit testing
``` > set up ESLint, Prettier, and Husky for code formatting and pre-commit hooks
```Tips:
- Ask for modern development best practices
- Request configuration for your specific tech stack
- Include deployment preparation in your setup
Generate comprehensive tests
Suppose you need to add thorough testing coverage to your application.
> identify which components and functions need test coverage
``` > create comprehensive unit tests for the user authentication service
``` > write integration tests for the shopping cart functionality
``` > set up Cypress tests for the complete user registration flow
```Tips:
- Ask for tests that cover edge cases and error conditions
- Request both positive and negative test scenarios
- Include tests for user interactions and API calls
Deploy applications
Suppose you need to deploy your application to production.
> optimize my React app for production deployment
``` > set up deployment to Vercel with environment variables
``` > create GitHub Actions workflow for automated testing and deployment
``` > add error tracking and performance monitoring to the deployed app
```Tips:
- Specify your preferred deployment platform
- Ask for environment-specific configurations
- Include monitoring and error handling setup
Work with databases
Suppose you need to design and implement database functionality.
> design a PostgreSQL schema for a social media application
``` > configure Prisma ORM with PostgreSQL for my Node.js API
``` > implement CRUD operations for users, posts, and comments
``` > create queries for user feed with pagination and filtering
```Tips:
- Specify your database technology and ORM preferences
- Ask for proper indexing and performance considerations
- Request data validation and security measures
Convert between technologies
Suppose you need to migrate or convert your project to different technologies.
> review my jQuery application and plan migration to React
``` > convert the user dashboard from jQuery to React component
``` > migrate CSS styles to Tailwind CSS classes
``` > convert JavaScript functions to TypeScript with proper types
```Tips:
- Plan migrations in small, manageable steps
- Ask for compatibility considerations during transition
- Request testing strategies for converted code
Learn and understand code
Suppose you need to understand an existing codebase or learn new concepts.
> explain the architecture and main components of this React application
``` > explain how the state management works in this Redux setup
``` > walk me through how user authentication is implemented here
``` > suggest modern alternatives to the patterns used in this codebase
```Tips:
- Ask for explanations in terms you understand
- Request examples and comparisons to familiar concepts
- Focus on one area at a time for better comprehension
Manage concurrent development workflows with Git worktrees
Imagine you need to tackle multiple coding tasks at the same time while keeping each Blackbox CLI instance completely separate for better context of changes and isolation of work.
Git worktrees let you check out different branches from the same repository into separate folders. Each folder gets its own working directory with independent files, but they all share the same Git history. Check out the official Git worktree guide for more details.
# Set up a new worktree with a fresh branch
git worktree add ../my-new-feature -b enhancement-ui
# Or set up a worktree for an existing branch
git worktree add ../my-app-fix fix-login-issue
```
This creates a separate folder with an independent copy of your repository. # Move to your worktree directory
cd ../my-new-feature
# Start Blackbox CLI in this isolated space
blackbox
``` cd ../my-app-fix
blackbox
``` # View all active worktrees
git worktree list
# Clean up a worktree when finished
git worktree remove ../my-new-feature
```Tips:
- Each worktree maintains its own file state, ideal for simultaneous Blackbox CLI sessions
- Modifications in one worktree don't impact others, ensuring Blackbox instances operate independently
- All worktrees access the same Git history and remote repositories
- For extended tasks, let Blackbox work in one worktree while you code in another
- Choose clear folder names to quickly identify each worktree's purpose
- Set up your development environment in each new worktree based on your project's needs, which may involve:
- JavaScript projects: Installing dependencies (
npm install,yarn install) - Python projects: Creating virtual environments or using package managers
- Other languages: Following your project's standard initialization steps
- JavaScript projects: Installing dependencies (
Ask Blackbox CLI about its own capabilities through direct queries
Want to learn more about Blackbox and its capabilities? Why not ask the agent itself for detailed insights and guidance. BlackBox CLI has access to its own documentation and can answer questions about its features and limitations.
Example queries to explore BLACKBOX AI
Start a session with blackbox and try these example prompts:
> what are the main features of Blackbox CLI and how do they help developers?> Can BlackBox CLI create a pull request for me?> What commands does BlackBox CLI support?> what are some advanced tips for getting the most out of BLACKBOX AI sessions?> how can I integrate Blackbox CLI with my existing development workflow?BlackBox CLI provides documentation-based answers to these questions. For executable examples and hands-on demonstrations, refer to the specific use-case sections above.
Tips:
- Phrase your questions clearly to get precise, helpful responses
- Follow up on answers with more detailed queries for deeper understanding
- Use the agent's knowledge to discover lesser-known features or optimizations
- Compare Blackbox capabilities with other tools by asking for side-by-side explanations
Compare multiple AI implementations with multi-agent execution
Suppose you want to see different approaches to solving the same problem and choose the best implementation. The /multi-agent command runs multiple AI agents in parallel, each working on a separate Git branch.
# Initialize Git if needed
git init
# Or navigate to an existing Git repository
cd your-project
``` > /multi-agent create a REST API with user authentication, JWT tokens, and CRUD operations for a blog
```
BLACKBOX CLI will automatically:
* Create separate branches for each agent (Claude, Blackbox, and Codex if OpenAI key is configured)
* Run all agents in parallel
* Each agent implements the task independently on its own branch # List all branches created
git branch
# Check out each branch to review
git checkout multi-agent-claude-<timestamp>
git checkout multi-agent-blackbox-<timestamp>
git checkout multi-agent-codex-<timestamp>
```Review each implementation for:
* Code quality and structure
* Error handling
* Security practices
* Performance considerations
* Documentation and comments # Switch to your main branch
git checkout main
# Merge the best implementation
git merge multi-agent-claude-<timestamp>
# Clean up unused branches
git branch -D multi-agent-blackbox-<timestamp>
git branch -D multi-agent-codex-<timestamp>
git branch -D multi-agent-gemini-<timestamp>
```Tips:
- Enable Codex: Configure your OpenAI API key with
blackbox configureto get a third implementation from GPT-5.2 Codex - Enable Gemini: Configure your GEMINI API key with
blackbox configureto get a fourth implementation - Complex Tasks: Use
/multi-agentfor complex features where multiple approaches provide valuable insights - Security-Critical Code: Ideal for authentication, payment processing, or data handling implementations
- Learning: Great way to see different AI coding styles and best practices
- Branch Naming: Branches are automatically named with timestamps for easy identification
- Git Required: This feature only works in Git-initialized directories
Example scenarios for multi-agent execution
Building a payment integration:
> /multi-agent implement Stripe payment processing with webhook handling and error recoveryCreating authentication systems:
> /multi-agent build OAuth2 authentication with Google and GitHub providersDeveloping complex algorithms:
> /multi-agent create a recommendation engine using collaborative filteringImplementing data processing:
> /multi-agent build a data pipeline with ETL operations and error handlingWhat agents are included?
Default (with BLACKBOX API key):
- Claude: Anthropic's Claude models - excellent for complex reasoning and detailed implementations
- Blackbox: BLACKBOX AI models - optimized for fast, efficient code generation
Additional (with OpenAI API & GEMINI API key key):
- Codex: OpenAI's GPT-5.2 Codex - advanced code generation with broad language support
- Gemini: Gemini's implementation for the multi agent.
Each agent works independently on its own branch, allowing you to compare different architectural decisions, coding patterns, and implementation strategies. This is particularly valuable for learning and ensuring code quality.