Skip to main content
The qckfx CLI is a powerful headless AI coding assistant designed for terminal workflows, automation, and CI/CD pipelines. This guide will get you running your first AI coding task in minutes.
For senior devs who want to get started immediately:
  1. Install: npm install -g @qckfx/agent
  2. Initialize: qckfx init (gets you our production agent configs)
  3. Set API key: export LLM_API_KEY="your-key" and export LLM_BASE_URL="your-provider-url"
  4. Hello World: qckfx "Hello, world!"
  5. Real task: qckfx "What does this repository do?"
Quick links for deeper exploration:Pro tip: Use qckfx -c to continue conversations, qckfx -m model-name to switch models mid-conversation, and qckfx (no arguments) for interactive mode with multi-line input and smart paste handling.

​
System Requirements

Operating Systems

  • macOS 10.15 (Catalina) or newer
  • Ubuntu 20.04 / Debian 11 or newer
  • Windows 10/11 with WSL or Git-Bash

Software Requirements

  • Node.js 18+ (required)
  • git 2.23+ (optional - for repo features)
  • 4 GB RAM minimum
Windows Users: The CLI requires a Unix-like environment. Use WSL (recommended) or Git-Bash for the best experience.

​
Quick Installation

​
1. Install the CLI globally

npm install -g @qckfx/agent
Do NOT use sudo npm install -g as this can lead to permission issues and security risks.

​
2. Initialize your project with default agents

Get started quickly with the same agents we use to develop qckfx: 
qckfx init
This creates a .qckfx directory with essential agent configurations:
  • advanced-agent.json - General-purpose coding agent with browser sub-agent, uses OpenAI o3 for orchestration and Claude Code for implementation
  • agent-editor.json - Specialized for editing system prompts in agent configuration files
  • commit.json - Helps write good commit messages
  • sub-agents/browser.json - Codebase research capabilities using GPT-4.1-nano for cost-efficient local file analysis
  • sub-agents/coder.json - Advanced coding assistance
The init command gives you the exact same agent configurations that the qckfx development team uses daily. It’s the fastest way to get productive with qckfx.

​
3. Set up your LLM provider

qckfx works with any OpenAI-compatible API. Set your environment variables: 
export LLM_API_KEY="sk-ant-your-secret-key"
export LLM_BASE_URL="https://api.anthropic.com/v1/"
Add these to your shell profile (.bashrc, .zshrc, etc.) to persist them across sessions.

​
4. Run your first command

qckfx "Hello, world!"
If everything is set up correctly, qckfx will respond and you’re ready to go!

​
Your First Real Task

Let’s try something more practical. Navigate to any code repository and run: 
# Analyze your codebase
qckfx "What does this repository do? Give me a high-level overview."

# Fix common issues
qckfx "Check for any obvious bugs or issues in the codebase"

# Get help with specific files
qckfx "Explain what the main entry point file does"

​
Continuing Conversations

qckfx automatically saves your conversation history. Use the -c flag to continue where you left off: 
# Start a conversation
qckfx "Analyze the auth.js file and identify potential improvements"

# Continue the conversation later
qckfx -c "Now implement those improvements you suggested"

# Keep the conversation going
qckfx -c "Add unit tests for the changes you just made"
Sessions are saved per working directory, so you can have different ongoing conversations for different projects.

​
Interactive Mode

When you run qckfx without providing a prompt, the CLI enters interactive mode - a powerful feature that makes it easy to work with complex, multi-line inputs and pasted content.

​
Entering Interactive Mode

Simply run the command without any arguments: 
qckfx
You’ll see an interactive prompt where you can compose your request: 
>

​
Multi-line Input

Create multi-line prompts by ending lines with a backslash (\): 
> Analyze this codebase and create a comprehensive report that includes: \
  - Architecture overview \
  - Code quality assessment \
  - Security considerations \
  - Performance recommendations
The backslash tells qckfx that your input continues on the next line, allowing you to structure complex requests clearly.

​
Smart Paste Handling

Interactive mode intelligently handles pasted content, similar to Claude Code. When you paste large blocks of text, qckfx automatically:
  1. Detects the paste and replaces it with a compact placeholder like [paste #1 +25 lines]
  2. Keeps your buffer clean so you can see your actual prompt structure
  3. Substitutes the content at runtime when you submit your request
This makes it easy to include code snippets, error messages, or documentation in your prompts without cluttering the input buffer.

​
Example Interactive Session

> I'm getting an error when running my tests. Here's the error output: \
  [paste #1 +15 lines] \
  \
  And here's the relevant test file: \
  [paste #2 +42 lines] \
  \
  Can you help me debug this issue?

​
Submitting Your Request

Press Enter to submit your interactive prompt (or Ctrl+D as an alternative). qckfx will process your request with all pasted content properly included.
If your current line ends with a backslash (\), pressing Enter will continue to the next line instead of submitting. Only lines that don’t end with \ will submit when you press Enter.

​
When to Use Interactive Mode

Interactive mode is particularly useful for:
  • Complex prompts that span multiple lines
  • Including code snippets or error messages via paste
  • Structured requests with multiple requirements
  • Exploratory conversations where you want to compose thoughtfully
Interactive mode is perfect for detailed code reviews, debugging sessions, and complex refactoring requests where you need to include multiple code snippets or detailed context.

​
Beyond Basics: Advanced Patterns

​
Using Different Models for Different Tasks

Mix models strategically - use powerful models for planning and cheaper ones for implementation: 
# Use a powerful model for planning
qckfx -m openai/o1 "Create a comprehensive plan for refactoring this auth system"

# Use a cheaper model to implement the plan (continuing the session)
qckfx -c -m openai/gpt-4o-mini "Implement the auth refactoring plan from above"

​
Adding Specialized Capabilities with Sub-agents

Sub-agents give your main agent specialized tools and capabilities: 
# Add codebase research capabilities
qckfx --with-subagent browser "Analyze the codebase structure and identify patterns"

# Add multiple specialized agents for comprehensive analysis
qckfx --with-subagent browser database "Analyze our data architecture and research modern alternatives"

# Continue a conversation with sub-agents
qckfx -c --with-subagent security "Now audit the security of the changes we discussed"

​
Configuration Preview

For complex workflows, create agent configuration files: 
// .qckfx/my-agent.json
{
  "defaultModel": "claude-sonnet-4",
  "systemPrompt": "You are a senior full-stack developer specializing in secure, scalable applications.",
  "tools": ["bash", "file_read", "file_write", "grep", "glob"]
}

# Use your custom agent
qckfx -a my-agent "Review this codebase for security and performance issues"

​
Common CLI Patterns

​
Quick Model Selection

# Use a specific model for one command
qckfx -m openai/gpt-4o "Refactor the auth.js file"

# Use a different provider
qckfx --url https://api.openai.com/v1 --api-key sk-... -m gpt-4o "Fix the tests"

​
Interactive vs Non-Interactive Modes

# Interactive mode - for complex, multi-line prompts
qckfx  # Enters interactive mode with paste handling

# Non-interactive mode - for scripts and automation
qckfx "commit my changes with a descriptive message"

# Run with specific configuration
qckfx -a ./my-agent-config.json "Review the latest changes"

​
Git Integration

# Analyze recent changes
qckfx "What changed in the last 3 commits?"

# Help with merge conflicts
qckfx "I have merge conflicts, help me resolve them"

# Create commits and PRs
qckfx "commit my changes and create a pull request"

​
Safety and Security

Local Execution Warning: The CLI can make real changes to your codebase when run locally. Always:
  • Work in a git repository with committed changes
  • Review changes before accepting them
  • Consider using sandboxed environments for untrusted code
  1. Use version control: Always work in a git repository
  2. Commit frequently: Save your work before running qckfx
  3. Review changes: Check what qckfx modified before committing
  4. Sandbox for automation: Use Docker or remote environments for CI/CD

​
Next Steps

Troubleshooting

Solutions for common CLI installation and usage issues

Advanced Configuration

Create custom agent configurations with specialized tools and prompts

GitHub Actions

Set up qckfx to run automatically in your CI/CD pipeline

Sub-agent Quickstart

Add specialized capabilities like web research, security auditing, and database design

Mixed Model Workflows

Use different models strategically within conversations for cost optimization

Agent Self-Improvement

Let agents analyze and improve their own system prompts automatically

​
Troubleshooting Quick Fixes

Make sure you installed globally and that your npm global bin directory is in your PATH:
npm list -g @qckfx/agent  # Should show the package
npm config get prefix     # Check your global prefix
Don’t use sudo with npm. Instead, configure npm to use a different directory:
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
Verify your environment variables are set correctly:
echo $LLM_API_KEY    # Should show your key
echo $LLM_BASE_URL   # Should show your provider URL

​
What’s Next?

Now that you have the CLI working, you can:
  • Automate your workflow: Use qckfx in scripts and CI/CD pipelines
  • Customize behavior: Create agent configuration files for specific tasks
  • Integrate with tools: Combine qckfx with your existing development tools
  • Scale up: Consider the SDK if you need programmatic control for applications
⌘I