cliq

Your AI copilot for the command line

Why cliq • Features • Installation • Quick Start • Usage • TUI Mode • Contributing

---

🧠 Why cliq?

The terminal is the most powerful tool on a developer's machine — but it's also the most unforgiving. One wrong flag, one misremembered syntax, and you're deep in man pages or Stack Overflow tabs.

cliq changes that. It's an AI-powered copilot that sits right inside your terminal. Think of it as having a senior engineer next to you who:

• Understands what you mean — describe your intent, get the exact command
• Knows your project — auto-detects your stack, tools, and platform
• Watches your back — catches dangerous commands before they execute
• Reviews your code — analyzes files and suggests improvements on the spot
• Remembers your workflow — bookmarks, history, and instant recall

It's not a chatbot. It's not a wrapper. It's a context-aware, safety-first command line copilot with a full interactive terminal UI.

# You think it...
cliq "find all memory leaks in the running node processes"

# ...cliq handles the rest.

✨ Features

Feature	Description
AI Copilot	Describe intent in natural language → get precise, executable commands
Interactive TUI	Full-screen chat interface built with React + Ink — not just a one-shot CLI
Context-Aware Intelligence	Auto-detects your stack (Node, Python, Rust, Go, Docker, etc.) and tailors commands
Safety Guardrails	Catches destructive commands (rm -rf, DROP TABLE, force push) with warnings
Multi-Provider	OpenAI, OpenRouter, or fully local with Ollama — your choice, your privacy
Code Review	Point cliq at any file and get AI-driven analysis and suggestions
Command Explanations	Don't just run commands blindly — understand what they do
Workflow Memory	Bookmarks, command history, and instant ! recall for repeat tasks
Cross-Platform	Windows, macOS, Linux — works everywhere
Script-Friendly	Quiet mode (-q) for piping into automation workflows

📦 Installation

From npm (Recommended)

npm install -g cliq

From Source

git clone https://github.com/PremKudale/cliq.git
cd cliq
npm install
npm link

🚀 Quick Start

1. Set up your AI provider:

cliq --setup

2. Just tell it what you need:

cliq "find which process is hogging port 3000"
cliq "undo my last git commit but keep the changes"
cliq "show me all docker containers eating memory"

3. Or drop into interactive mode:

cliq -i

🔧 Provider Setup

Choose the provider that fits your workflow:

OpenAI

Best for speed and reliability.

cliq --setup
# → Select "OpenAI" → Enter your API key

Or: export OPENAI_API_KEY=sk-...

Models: gpt-4o-mini (recommended), gpt-4o, gpt-4-turbo

OpenRouter

One API key, access to dozens of models — Claude, GPT, Gemini, Llama, Mistral.

cliq --setup
# → Select "OpenRouter" → Enter your API key

Or: export OPENROUTER_API_KEY=sk-or-...

Ollama (Local / Free / Private)

Run everything locally. No API keys, no costs, no data leaves your machine.

ollama serve
ollama pull llama3.2
cliq --setup
# → Select "Ollama" → Choose your model

📖 Usage

The Basics

# Describe what you want — cliq figures out the how
cliq "list all files modified in the last 24 hours"

# Get an explanation of what the command does before running it
cliq -e "find all TODO comments in javascript files"

# Copy to clipboard instead of executing
cliq -C "compress this folder as a zip"

# Script mode — outputs only the raw command
cliq -q "get the current git branch"

# Instant replay — repeat the last successful command
cliq !

Bookmarks — Save Your Go-To Commands

cliq --save deploy "deploy to production with docker"
cliq --run deploy
cliq --bookmarks
cliq --delete-bookmark deploy

Command History

cliq --history
cliq !                    # Repeat last command
cliq --clear-history

Code Review

cliq -f src/index.js
cliq -f api/auth.py -r "check for security vulnerabilities"
cliq -f utils.js -r "optimize for performance"

Context Detection

cliq scans your working directory and adapts:

cliq --context

Detected Context

  Platform:       Windows
  Project types:  Node.js, TypeScript, Git repository
  Available tools: npm, npx, tsc, git

Detected stacks: Node.js, Python, Rust, Go, Java (Maven/Gradle), Ruby, PHP, Docker, Next.js, Vite, TypeScript, Bun, and more.

🖥️ Interactive TUI Mode

This is where cliq really shines. Launch it with:

cliq -i

You get a full-screen, chat-style terminal interface:

• ASCII art header with live provider/model info
• Conversational interface — ask questions, see commands, review output
• Inline command preview with one-key actions
• Animated loading states with rotating spinners
• Danger highlighting — risky commands are flagged visually
• Query history — navigate with ↑/↓ arrows

Keyboard Shortcuts

Key	Action
Enter	Submit your query
y	Execute the suggested command
n	Skip / cancel
e	Explain the command
c	Copy to clipboard
↑ / ↓	Navigate query history
Ctrl+L	Clear the chat
Ctrl+C	Exit

🛡️ Safety Guardrails

cliq doesn't blindly execute. It pattern-matches against 16+ known dangerous operations and forces explicit confirmation:

Detected Pattern	Warning
rm -rf	Recursive file deletion
del /s	Recursive deletion (Windows)
DROP TABLE / TRUNCATE	Database destruction
DELETE FROM table;	Mass row deletion
git push --force	History overwrite
git reset --hard	Discard all changes
chmod 777	Overly permissive permissions
mkfs.* / format C:	Disk formatting
shutdown / reboot	System power operations
npm publish	Registry publishing
curl ... | bash	Remote script execution

📋 CLI Reference

cliq [options] [query]

Option	Alias	Description
--setup		Configure AI provider
--config		Show current configuration
--help	-h	Show help
--version	-v	Show version
--interactive	-i	Launch interactive TUI
--history	-H	Show command history
--bookmarks	-b	Show saved bookmarks
--context	-c	Show detected project context
--explain	-e	Explain the suggested command
--copy	-C	Copy command to clipboard
--quiet	-q	Output only the command
--save <name>		Bookmark a command
--run <name>		Run a bookmark
--delete-bookmark <name>		Delete a bookmark
--clear-history		Clear history
--file <path>	-f	File for code review
--review <prompt>	-r	Review instruction

🏗️ Architecture

cliq/
├── index.js                  # CLI entry point & argument routing
├── src/
│   ├── lib/                  # Core intelligence
│   │   ├── ai.js             # Multi-provider AI client
│   │   ├── config.js         # Persistent config, history & bookmarks
│   │   ├── context.js        # Project stack detection engine
│   │   ├── security.js       # Dangerous command pattern matching
│   │   ├── utils.js          # File I/O & formatting
│   │   └── validation.js     # Input sanitization & validation
│   └── tui/                  # Interactive terminal UI
│       ├── App.js            # Root component & state machine
│       ├── Header.js         # ASCII branding & provider display
│       ├── ChatLog.js        # Message renderer & welcome screen
│       ├── InputBar.js       # Input with animated loading states
│       ├── CommandPreview.js # Command display with action keys
│       ├── StatusBar.js      # Status + keyboard hint bar
│       └── theme.js          # Color palette & visual constants
├── __tests__/                # Jest test suite
├── .github/workflows/ci.yml  # CI across 3 OS × 3 Node versions
└── package.json

⚙️ Configuration

All state lives in ~/.cliq/:

File	Purpose
config.json	Provider, model, API key
history.json	Last 50 commands with status
bookmarks.json	Saved command bookmarks

🧑‍💻 Development

git clone https://github.com/PremKudale/cliq.git
cd cliq
npm install

npm test                # Run tests
npm run test:coverage   # Coverage report
npm run lint            # ESLint
npm run format          # Prettier

The CI pipeline runs on every push: 3 OS × 3 Node.js versions = 9 environments tested.

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for the full guide.

fork → branch → code → test → PR

📄 License

ISC © Prem Kudale

---

Think it. cliq it. Done.
_{Built by @PremKudale}