Overview

The cognitivess CLI is the fastest way to run Cognitivess-1 inside your coding tools — Claude Code, OpenClaw, Hermes and Codex — through one API key. It also runs any GGUF model fully offline on your own machine via the Cognitivess engine, with no billing and no network calls.

Installation

One-liner install (Linux / macOS / WSL — needs only Python 3):

curl -fsSL https://api.cognitivess.com/install | sh

This downloads the cognitivess binary and puts it on your PATH. Verify it landed:

cognitivess --help

cognitivess login

Save your API key once. It is prompted securely (not echoed) and stored at ~/.config/cognitivess/config.json (locked to your account). You only do this for gateway mode — local mode needs no key.

cognitivess login

# or pass it inline:
cognitivess login --key "<YOUR_API_KEY>"

# self-host / alternate gateway:
cognitivess login --base-url https://api.cognitivess.com

Your key looks like ssh-ed25519 AAAA... — generate one in the dashboard. It is shown only once, so store it securely.

cognitivess launch <tool>

Launch a coding tool under Cognitivess-1. The CLI sets the right base_url + API key + model env vars for each tool, so the tool speaks to Cognitivess-1 as if it were the native backend.

Supported tools

Gateway mode (default)

# Run Claude Code under Cognitivess-1
cognitivess launch claude

# Run Codex, passing tool-specific flags after "--"
cognitivess launch codex -- -m Cognitivess-1

# Pin a model alias (c1, cognitivess-1, cognitivess)
cognitivess launch claude --model c1

Local mode — run GGUF models offline

Add --local <name|path> to run a model on your own machine via the cognitivess-engine. The CLI auto-installs the Cognitivess engine the first time, starts the server on 127.0.0.1:8080, and points the tool at it. No key needed, nothing leaves your machine.

# Run a pulled model by name (see `cognitivess pull` below)
cognitivess launch claude --local qwen2.5-0.5b

# Or point at a .gguf file directly (backward-compat)
cognitivess launch claude --local ./my-model.gguf

# Different port / host if 8080 is taken
cognitivess launch hermes --local qwen2.5-0.5b --port 8081

# Use a custom cognitivess-engine binary
cognitivess launch claude --local qwen2.5-0.5b --engine-path /usr/local/bin/cognitivess-engine

Flags

• <tool> — one of claude, openclaw, hermes, codex.
• --model, -m — model name or alias (gateway mode only). Aliases: c1, cognitivess-1, cognitivess1, cognitivess.
• --local <MODEL.gguf> — run a local model offline via the Cognitivess engine instead of the gateway. Accepts a catalog name (e.g. qwen2.5-0.5b) or a direct .gguf path.
• --port — local server port (default 8080).
• --host — local server host (default 127.0.0.1).
• --path — path to the tool's binary (overrides <TOOL>_BIN env / default).
• --engine-path — path to the cognitivess-engine binary (default: auto-download, or COGNITIVESS_ENGINE_BIN env).
• -- ... — everything after -- is passed through to the tool (e.g. -c "continue", --resume).

cognitivess models

List available models — gateway models by default, or local GGUF models with --local.

# Gateway models (pricing, context, needs key)
cognitivess models

# Locally pulled .gguf models (offline storage, no key)
cognitivess models --local

cognitivess pull <name>

Download a local .gguf model from Hugging Face into ~/.config/cognitivess/models/. Names come from the gateway catalog — run cognitivess pull with no argument to see them all, marked with ✓ pulled for what you already have.

# List the catalog
cognitivess pull

# Download a model
cognitivess pull qwen2.5-0.5b

# Re-download even if already pulled
cognitivess pull qwen2.5-0.5b --force

# Skip the engine install (model only)
cognitivess pull qwen2.5-0.5b --no-engine

# Then run it locally
cognitivess launch claude --local qwen2.5-0.5b

cognitivess serve <model>

Start the Cognitivess web UI server with a local model and keep it running until Ctrl+C. Unlike launch --local (which starts the same server and a coding tool on top of it), serve starts only the server — you interact with the model through your browser at http://127.0.0.1:8080, not via a CLI tool. Offline, no key, no billing.

# Serve a pulled model by name (browser opens automatically)
cognitivess serve qwen2.5-0.5b

# Or point at a .gguf file directly
cognitivess serve ./path/to/model.gguf

# Different port / host
cognitivess serve qwen2.5-0.5b --port 8081 --host 0.0.0.0

# Use an engine already in PATH (skip the auto-install)
cognitivess serve qwen2.5-0.5b --no-engine

# Force a fresh install of the branded web UI
cognitivess serve qwen2.5-0.5b --force-webui

# Enable the web UI's built-in tools (read_file, grep_search, file_glob_search)
cognitivess serve qwen2.5-0.5b --tools all

# ...or just a subset
cognitivess serve qwen2.5-0.5b --tools read_file,grep_search

Flags

• <model> — model name from the catalog (e.g. qwen2.5-0.5b) or a direct .gguf path.
• --engine-path — path to the cognitivess-engine binary (default: auto-download, or COGNITIVESS_ENGINE_BIN env).
• --no-engine — don't auto-install the engine; use one already in PATH.
• --port — server port (default 8080).
• --host — server host (default 127.0.0.1).
• --no-browser — don't auto-open the browser (the URL is still printed).
• --force-webui — re-install the branded web UI theme even if it's already cached.
• --tools — enable the web UI's built-in tools (passed to the engine as --tools). Use --tools all for every tool, or a comma list: read_file,grep_search,file_glob_search. Without it, the web UI shows a "run ... with --tools" hint and tools are disabled. Experimental: the model can access local files on your machine — local use only, opt in explicitly.

cognitivess rm <name>

Delete a locally pulled model (frees disk; also removes its sidecar .meta.json).

cognitivess rm qwen2.5-0.5b

# Skip the confirmation prompt
cognitivess rm qwen2.5-0.5b -y

cognitivess me

Check your saved key and current usage / spend over the last 30 days.

cognitivess me

Where things live

Troubleshooting

• HTTP 404 on pull — the catalog entry pointed at a file that moved on Hugging Face. The CLI now resolves case mismatches and sharded files automatically; if it still fails, check the repo's file list on HF.
• The server did not become ready — the model may be too large for your RAM, the port may be in use (try --port), or the .gguf is corrupt.
• Tool says "invalid key" in local mode — you passed a real API key to a tool whose backend is the local server. In local mode the key is always local; it's set automatically, so don't override ANTHROPIC_API_KEY / OPENAI_API_KEY yourself.
• Web UI at :8080 asks for a key — type local. That's the engine's web UI, not the gateway.
• Branding (logo / colors) missing in the web UI — the theme pack couldn't be downloaded from the gateway (network/firewall), so the CLI fell back to the default engine UI. Re-run cognitivess serve <model> --force-webui once you're back online.