Skip to main content
The qckfx command is the primary interface for running AI agents from the command line. It supports various options for model selection, configuration, session management, and more.

​
Syntax

qckfx [options] [prompt...]
qckfx init

​
Options

​
Agent Configuration

​
-a, --agent <file>
string
Path to an agent definition JSON file. Supports smart path resolution:
  • Direct file paths (relative or absolute)
  • Auto-appends .json extension if missing
  • Looks in .qckfx/ directory for shorthand names
​
-m, --model <model>
string
default:"gemini-2.5-pro"
Model to use for this execution. Overrides the default model in agent configuration.

​
API Configuration

​
--api-key <key>
string
Override the LLM_API_KEY environment variable for this execution.
​
--url <baseUrl>
string
Override the LLM_BASE_URL environment variable for this execution.

​
Session Management

​
-c, --continue
boolean
Continue the most recent session for the current working directory. Sessions are automatically saved after each execution.

​
Sub-agents

​
--with-subagent <name...>
string[]
Add one or more sub-agent tools for this execution. Sub-agents are resolved from .qckfx/sub-agents/<name>.json.

​
Output Control

​
-q, --quiet
boolean
Suppress all output except the final response or errors. Perfect for CI/CD environments and GitHub Actions where you want clean, minimal output. When using this flag, a prompt must be provided as arguments since interactive mode is disabled.

​
Validation

​
-v, --validate <file>
string
Validate an agent definition file and exit. Does not execute the agent.

​
Prompt

​
[prompt...]
string
The prompt to send to the agent. If not provided, the CLI will enter interactive mode.

​
Commands

​
init

The init command sets up a new project with default agent configurations: 
qckfx init
This command:
  • Creates a .qckfx directory in the current working directory
  • Installs essential agent configurations used by the qckfx development team:
    • 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 is the fastest way to get started with qckfx. It gives you the same agent configurations that the qckfx team uses for daily development.
If a .qckfx directory already exists, the init command will overwrite existing files with the same names.

​
Examples

​
Project Initialization

# Initialize a new project with default agents
qckfx init

​
Basic Usage

# Simple prompt
qckfx "What files are in this directory?"

# Multi-word prompt
qckfx "Analyze the codebase and find potential security issues"

​
Model Selection

# Use a specific model
qckfx -m claude-sonnet-4 "Explain this code"

# Use with OpenAI models
qckfx -m gpt-4.1-mini "Write unit tests for this function"

​
Agent Configurations

# Use a specific agent config
qckfx -a security-agent.json "Scan for vulnerabilities"

# Use shorthand (looks for .qckfx/security-agent.json)
qckfx -a security-agent "Scan for vulnerabilities"

# Validate configuration without running
qckfx --validate security-agent.json

​
Session Management

# Start a new conversation
qckfx "Hello, I need help with my project"

# Continue the previous conversation
qckfx --continue "Can you also check the tests?"

# Continue with a specific model
qckfx -c -m claude-sonnet-4 "Use a more powerful model for this"

​
Sub-agents

# Add a single sub-agent
qckfx --with-subagent browser "Analyze the codebase structure and identify patterns"

# Add multiple sub-agents
qckfx --with-subagent browser database "Analyze our data architecture"

# Combine with agent config
qckfx -a my-agent --with-subagent browser "Enhanced analysis with codebase research"

​
API Configuration

# Override API key
qckfx --api-key sk-your-key "Test with different credentials"

# Use custom base URL (e.g., LiteLLM proxy)
qckfx --url http://localhost:8001 "Use local proxy"

# Combine both
qckfx --api-key sk-key --url http://localhost:8001 "Custom setup"

​
Quiet Mode for CI/CD

# Clean output for CI/CD environments
qckfx --quiet "Analyze the codebase for security issues"

# Combine with other options for automated workflows
qckfx -q -a security-agent "Scan for vulnerabilities"

# Perfect for GitHub Actions and automated scripts
qckfx --quiet --model claude-3-haiku-20240307 "Quick code review"

​
Interactive Mode

When you run qckfx without a prompt, it enters interactive mode: 
$ qckfx
? Enter prompt ›
Type your prompt and press Enter to execute. The prompt cannot be empty.

​
Path Resolution

The CLI uses smart path resolution for agent configurations:
  1. Direct Path: If the file exists as specified, use it
  2. Auto Extension: If missing .json, append it and check again
  3. Convention Directory: Look in .qckfx/<name>.json
  4. Fallback: Return the direct path (will cause error if not found)
# Uses ./configs/my-agent.json
qckfx -a ./configs/my-agent.json "prompt"

​
Exit Codes

CodeMeaning
0Success
1Error (validation failed, execution error, etc.)

​
Error Handling

The CLI provides clear error messages for common issues:
  • Invalid Configuration: Shows validation errors with specific details
  • Missing Files: Reports which files couldn’t be found
  • API Errors: Displays model provider error messages
  • Session Errors: Warns about session loading failures but continues
If session loading fails when using --continue, the CLI will warn you but start a fresh session instead of failing.

​
Performance Tips

  • Use --continue to maintain context across multiple interactions
  • Leverage sub-agents for specialized tasks instead of complex prompts
  • Validate configurations with --validate before deployment
  • Use shorter model names when possible (e.g., claude-sonnet-4 vs full model IDs)
  • Use --quiet in CI/CD environments to reduce log noise and improve performance