Skip to main content
qckfx offers two distinct products designed for different use cases. This guide will help you choose the right one for your needs.

​
Quick Decision Matrix

Choose CLI if you:

✅ Want to automate coding tasks in CI/CD
✅ Need AI assistance while coding in terminal
✅ Want to run headless automation workflows
✅ Prefer simple command-line interfaces
✅ Need GitHub Actions integration
✅ Want minimal setup and configuration

Choose SDK if you:

✅ Are building applications with AI features
✅ Need programmatic control over agents
✅ Want to create custom user interfaces
✅ Need streaming updates and event handling
✅ Require fine-grained permission control
✅ Are building commercial products

​
Detailed Comparison

​
Use Case Scenarios

  • Individual Developer
  • Team Automation
  • Application Developer
  • Enterprise Integration
Best Choice: CLIAs a solo developer, you want quick AI assistance while coding:
# Quick help while coding
qckfx "explain this error message"
qckfx "fix the failing tests"
qckfx "refactor this function to be more readable"
Why CLI wins:
  • Instant access from any terminal
  • No application development needed
  • Works in any codebase immediately
  • Perfect for ad-hoc tasks

​
Technical Capabilities

FeatureCLISDKNotes
InstallationGlobal npm installProject dependencyCLI is system-wide, SDK is per-project
UsageCommand lineProgrammatic APICLI for terminal, SDK for applications
ConfigurationJSON files + CLI flagsCode + JSON filesSDK offers more runtime flexibility
ExecutionHeadless by designLocal/Docker/RemoteSDK offers more environment options
Streaming❌✅SDK provides real-time updates
Session Management❌✅SDK maintains conversation context
Permission ControlBasicAdvancedSDK allows custom permission logic
Error HandlingBasicAdvancedSDK provides detailed error events
UI Integration❌✅SDK designed for custom interfaces

​
Security Considerations

CLI Security Note: The CLI is designed for headless automation but can run locally. When running in your local terminal, it can make real changes to your codebase. Use appropriate caution and always work in version-controlled repositories.
SDK Security Note: The SDK provides multiple execution environments (local, Docker, remote) and fine-grained permission controls, making it suitable for both development and production use cases.

​
Performance & Scalability

CLI Performance:
  • Optimized for single-task execution
  • Minimal overhead for automation scripts
  • Best for batch processing and CI/CD
SDK Performance:
  • Designed for long-running applications
  • Session state management for efficiency
  • Caching and connection pooling
  • Better for interactive applications

​
Learning Curve

CLI Learning Curve

Beginner Friendly
  • Install and run immediately
  • Familiar command-line interface
  • No programming required
  • Great for getting started
Time to productivity: Minutes

SDK Learning Curve

Developer Focused
  • Requires TypeScript/JavaScript knowledge
  • Understanding of async programming
  • Application architecture decisions
  • More configuration options
Time to productivity: Hours to days

​
Migration Paths

​
From CLI to SDK

If you start with the CLI and later need SDK features: 
// Your CLI command
// qckfx "analyze this codebase"

// Equivalent SDK code
const agent = new Agent({
  defaultModel: 'anthropic/claude-sonnet-4',
  systemPrompt: 'You are a helpful AI coding agent...'
});

const result = await agent.processQuery('analyze this codebase');

​
From SDK to CLI

If you have SDK code and want to automate it: 
// Create agent-config.json from your SDK config
{
  "defaultModel": "anthropic/claude-sonnet-4",
  "systemPrompt": "You are a helpful AI coding agent...",
  "tools": ["bash", "file_read", "file_edit", "grep"]
}

# Run with CLI
qckfx -a agent-config.json "analyze this codebase"

​
Common Misconceptions

Not necessarily. The CLI supports custom agent configurations, sub-agents, and all the same tools as the SDK. The main difference is the interface (command-line vs programmatic API).
Partially true. While they share the same core engine, the CLI is optimized for headless operation and automation, while the SDK is optimized for application integration.
False. You can use both in the same project. For example, use the CLI for CI/CD automation and the SDK for a custom developer dashboard.

​
Decision Framework

Ask yourself these questions:
  1. Are you building an application?
    • Yes → SDK
    • No → CLI
  2. Do you need a custom user interface?
    • Yes → SDK
    • No → CLI
  3. Is this for automation/CI/CD?
    • Yes → CLI
    • No → Consider both
  4. Do you need real-time streaming updates?
    • Yes → SDK
    • No → Either works
  5. Do you need session management?
    • Yes → SDK
    • No → Either works

​
Next Steps

Start with CLI

Get up and running in minutes with the command-line interface

Start with SDK

Begin building applications with embedded AI agents
Still not sure? Start with the CLI - it’s easier to get going and you can always add the SDK later if you need programmatic control.
⌘I