cliara 0.4.5

An AI-powered shell that understands natural language and macros

Cliara

An AI-powered shell that understands natural language and macros.

---

What is Cliara?

Cliara wraps your existing shell (bash, zsh, PowerShell, cmd) and adds:

Feature	Description
Natural language	? <query> — describe what you want, get shell commands
Cliara Cloud	Sign in with GitHub, 150 free queries/month, no API key
Macros	Create, edit, run reusable command sequences
Semantic history	? find when I fixed the login — search past commands by meaning
Smart push	push — auto-commit message, branch detection, one command
Smart deploy	deploy — auto-detect Vercel, Netlify, Docker, PyPI, and deploy
Safety checks	Destructive commands show a diff preview before running
Fix failed commands	? fix — AI suggests corrections after a command fails

All your normal commands work unchanged. Cliara is a thin layer on top of your shell.

---

Installation

Option 1: pipx (recommended)

Best for CLI tools — installs in an isolated environment and adds to PATH automatically.

pip install pipx
pipx ensurepath   # Add pipx bin to PATH (restart terminal if needed)
pipx install cliara

Option 2: pip

pip install cliara

If cliara isn't recognized, use:

python -m cliara.main

Option 3: From source (development)

git clone https://github.com/HreemPandya/cliara-app.git
cd cliara-app
pip install -e .

Optional Dependencies

To enable PostgreSQL support, install with:

pip install cliara[postgres]

---

First Run / Setup

1. Start Cliara: cliara
2. First time? A browser opens for GitHub login. Authorize once.
3. Done. Your token is saved to ~/.cliara/token.json and loads automatically on every start.

Authentication / Cloud Login Flow

• The OAuth login flow opens your browser to sign in with GitHub.
• Once authenticated, your token is stored at ~/.cliara/token.json.

Alternative: Bring Your Own API Key

Prefer Groq, Gemini, Ollama, or OpenAI? Run setup-llm inside Cliara to configure. Free options include Groq and Google AI Studio.

---

Usage

Normal Commands (Pass-Through)

Just type commands as usual - they go straight to your shell:

cliara:proj ❯ ls -la
cliara:proj ❯ cd myproject
cliara:proj ❯ git status
cliara:proj ❯ npm install

Natural Language Commands

Use ? prefix for natural language:

cliara:proj ❯ ? list files in this directory
cliara:proj ❯ ? kill process on port 3000
cliara:proj ❯ ? find when I ran the deploy
cliara:proj ❯ ? fix                    # Fix the last failed command

Macros

cliara:proj ❯ macro add build          # Create a macro
cliara:proj ❯ build                    # Run it
cliara:proj ❯ macro save last as test  # Save last command as macro

Smart Commands

cliara:proj ❯ push                     # Smart push (auto-commit message + branch)
cliara:proj ❯ deploy                   # Smart deploy (auto-detect project type)

Help

cliara:proj ❯ help                     # Full command reference

---

Database Setup and Migration

If using PostgreSQL as your backend, follow these steps:

1. Install PostgreSQL (see PostgreSQL Setup Guide).
2. Create Database and User:

# Connect to PostgreSQL
psql postgres

# Create database
CREATE DATABASE cliara;

# Create user
CREATE USER cliara WITH PASSWORD 'your_password_here';

# Grant privileges
GRANT ALL PRIVILEGES ON DATABASE cliara TO cliara;

# Exit
\q

3. Install Python Dependencies:

pip install psycopg2-binary

4. Configure Cliara:

Edit ~/.cliara/config.json:

{
  "storage_backend": "postgres",
  "postgres": {
    "host": "localhost",
    "port": 5432,
    "database": "cliara",
    "user": "cliara"
  }
}

---

Required Environment Variables

Copy .env.example to .env and fill in the values for your chosen provider. Only ONE LLM provider should be active at a time.

# ── Option A: OpenAI (cloud, requires API key) ────────────────────────────────
OPENAI_API_KEY=sk-proj-your-key-here

# ── Option B: Anthropic Claude (cloud, requires API key) ─────────────────────
ANTHROPIC_API_KEY=sk-ant-your-key-here

# ── Option C: Ollama (local, free, no key needed) ────────────────────────────
OLLAMA_BASE_URL=http://localhost:11434

---

Documentation

• Complete Guide — Full documentation
• Quick Start — Get started in 5 minutes
• Cliara Cloud Deployment — Self-host the backend
• PostgreSQL Setup — Scalable macro storage

---

Troubleshooting

Issue	Solution
cliara not recognized	Use python -m cliara.main or install with pipx install cliara
Connection error	Check network/firewall; try $env:CLIARA_GATEWAY_URL = "https://cliara-cloud-production.up.railway.app/v1"
Want BYOK instead	Run setup-llm inside Cliara for Groq, Gemini, Ollama, OpenAI

---

License

MIT