Quickstart: install Arka and run your first command

Install Arka on macOS, Linux, or Windows with pipx — no git clone — configure Gemini or Groq API keys, verify with arka doctor, and run your first natural-language terminal command in under five minutes.

Get Arka running on macOS, Linux, or Windows — no git clone or local build required. Install the published Python package, run arka setup, add an API key, and use arka from any terminal.

At a glance: Requires Python 3.11+, one LLM API key (Gemini or Groq recommended), and optionally fish shell for the full skill router. Recommended install: pipx install "arka-agent[chat]" → arka setup → arka doctor → arka ask "what is Rust?". Full docs: Introduction.

Watch the quickstart tutorial:

Arka quickstart — install, configure, and run your first command

Recommended path — pipx (or pip) install, then verify and ask:

1. Install

pipx install "arka-agent[chat]"
arka setup

arka doctor

arka ask "what is Rust?"

Before you begin

Arka uses a docs-as-code approach — this site is built on Mintlify and deployed at arka-agent.mintlify.site. To use Arka itself, you need:

• Python 3.11+
• At least one LLM API key (Gemini or Groq recommended for free tiers)
• fish shell for the full 70+ skill router (optional but recommended)

Install (no build from source)

Most users should install the arka-agent package directly. You do not need to clone the repo, run ./scripts/refetch.sh, or compile anything — pip / pipx downloads a ready-to-run CLI.

pipx (recommended)

Isolated install — best for daily terminal use. Requires pipx.

pipx install "arka-agent[chat]"
arka setup
arka doctor

If PyPI returns 404 (publish in progress), install the latest release straight from GitHub — still no local build:

pipx install "arka-agent[chat] @ git+https://github.com/Sumit884-byte/arka.git"
arka setup
arka doctor

pip / venv

Install into an existing virtual environment or user site-packages.

python3 -m pip install "arka-agent[chat]"
arka setup
arka doctor

GitHub fallback (no clone):

python3 -m pip install "arka-agent[chat] @ git+https://github.com/Sumit884-byte/arka.git"
arka setup

Git clone (contributors)

Only needed if you are developing Arka itself or patching the repo.

git clone https://github.com/Sumit884-byte/arka.git
cd arka
./scripts/refetch.sh --install
arka setup

Editable dev

For contributors working inside the repo with live code changes.

git clone https://github.com/Sumit884-byte/arka.git && cd arka
python3 scripts/sync_bundled.py
pip install -e ".[chat]"
arka setup

After install, which arka should print a path under pipx’s venv or your active Python environment. Run arka doctor — you should see Skills: full (70+) when fish is installed, or portable mode otherwise.

Use Arka from any terminal

Once installed, open a new terminal tab (so PATH picks up pipx) and run:

arka ask "what is Rust?"
arka "convert 100 USD to INR"
arka route "summarize this repo"
arka help

Optional — unlock the full 70+ skill router with fish shell:

brew install fish          # macOS
arka reload                # loads bundled config.fish

Without fish, Arka still works in portable mode: arka ask, calc, weather, plugins, and MCP.

Get started

1. Configure API keys

   Copy the example env file and add at least one provider key.

   cp .env.example ~/.config/arka/.env
   

   Minimum .env for a quick start:

   GEMINI_API_KEY=your_key_here
   GROQ_API_KEY=your_key_here
   AI_PREFERRED_PROVIDER=gemini
   AI_PREFERRED_MODEL=gemini-2.0-flash
   AGENT_SPEAK=1
   

   Config paths vary by OS. Linux uses ~/.config/arka/, macOS uses ~/Library/Application Support/arka/, and Windows uses %APPDATA%\arka\.

2. Verify the install

   Run diagnostics to confirm dependencies and API keys.

   arka doctor
   
3. Run your first command

   Ask a question and see Arka route it to the web answer skill.

   arka ask "what is Rust?"
   

   Try a few more:

   arka "convert 100 USD to INR"
   arka council "should I learn Rust?"
   arka quiz python
   arka route "convert 100 USD to INR"
   arka help
   
4. Personalize (optional)

   Pick interests and get skill recommendations tailored to you.

   arka personalize wizard
   arka personalize recommend
   

   See Personalize your Arka experience for interest tags and non-interactive flags.

5. Install fish shell (optional)

   Fish unlocks the full 70+ skill router. The pip package ships config.fish.

   # macOS
   brew install fish
   
   # Linux
   apt install fish
   
   # Windows
   scoop install fish
   

Optional extras

Extra	Adds
[chat]	Agno, web search, trafilatura, sympy, geopy
[voice]	vosk, sounddevice
[pdf]	PrivateGPT client
[charts]	matplotlib
[all]	Everything above

pip install "arka-agent[all]"

Next steps

Follow the sidebar in order, or jump to what you need:

How to code with Arka

Daily coding workflow — setup, edits, review, CI, and Cursor MCP.

CLI reference

All commands, aliases, and subcommands.

Skills catalog

What you can ask Arka to do.

How routing works

Offline rules, LLM fallback, and correction layer.

LLM configuration

Providers, failover, and per-skill models.

Configuration

Env vars, precedence, and built-in defaults.

Voice

Wake word, STT, and TTS setup.

Arka Council

Multi-persona deliberation.

Changelog

What’s new this week.