Examples

This page provides practical examples of using Flux-CLI for common development tasks.

Example 1: Understanding a Codebase

Ask Flux-CLI to explore and explain an unfamiliar codebase:

❯ Explore the project structure and explain how the authentication system works

What happens:

1. Agent calls list_dir to see the top-level structure
2. Agent calls grep to find authentication-related code
3. Agent reads key files to understand the auth flow
4. Agent provides a comprehensive explanation

Example 2: Refactoring Code

Ask Flux-CLI to refactor a function:

❯ Refactor the get_config() function in config/loader.py to use a cache pattern

What happens:

1. Agent reads config/loader.py to understand the current implementation
2. Agent plans the refactoring approach
3. Agent uses edit to make surgical changes
4. Agent verifies the changes are correct

Example 3: Debugging

Ask Flux-CLI to help debug an issue:

❯ The shell tool keeps timing out. Find the timeout configuration and explain why

Example 4: Multi-Step Task

Use the todos tool to track a complex task:

❯ I need to:
1. Add input validation to the WriteFileTool
2. Write tests for it
3. Update the documentation
Use todos to track this

Example 5: Web Research

Ask Flux-CLI to research a topic:

❯ Search for the latest best practices for Python project structure in 2024

Example 6: Using Sub-Agents

For complex codebase analysis, use sub-agents:

❯ Use the codebase investigator to understand how the hook system works

Example 7: Working with MCP Tools

If you have an MCP server connected:

❯ Use the filesystem MCP server to list all files in the project

Example 8: Session Persistence

Save and resume a complex session:

❯ /save
# Later, in a new session:
❯ /resume 550e8400-e29b-41d4-a716-446655440000
# Continue from where you left off

Best Practices

1. Be specific — Clear, specific prompts yield better results
2. Use todos — For multi-step tasks, let Flux-CLI track progress
3. Check stats — Monitor token usage with /stats to stay within limits
4. Save frequently — Use /save to preserve important sessions
5. Leverage sub-agents — For deep investigations, delegate to focused sub-agents