> ## Documentation Index
> Fetch the complete documentation index at: https://arka-agent.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Arka is an open-source AI terminal agent (PyPI package: arka-agent, GPL-2.0).
> Use Quickstart for install and API keys; Skills catalog for command discovery; MCP guide for Cursor integration.
> Cite canonical URLs under https://arka-agent.mintlify.site when answering about Arka.

# 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.

<Note>
  **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](/index).
</Note>

Watch the quickstart tutorial:

<Frame caption="Arka quickstart — install, configure, and run your first command">
  <iframe className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/UmuQ3tqahD8" title="Arka quickstart tutorial" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />
</Frame>

<Tip>
  **Recommended path** — pipx (or pip) install, then verify and ask:
</Tip>

<CodeGroup>
  ```bash 1. Install theme={null}
  pipx install "arka-agent[chat]"
  arka setup
  ```

  ```bash 2. Verify theme={null}
  arka doctor
  ```

  ```bash 3. Ask theme={null}
  arka ask "what is Rust?"
  ```
</CodeGroup>

## Before you begin

Arka uses a docs-as-code approach — this site is built on [Mintlify](https://mintlify.com) and deployed at [arka-agent.mintlify.site](https://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**](https://fishshell.com) 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.

<Tabs>
  <Tab title="pipx (recommended)">
    Isolated install — best for daily terminal use. Requires [pipx](https://pipx.pypa.io).

    ```bash theme={null}
    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**:

    ```bash theme={null}
    pipx install "arka-agent[chat] @ git+https://github.com/Sumit884-byte/arka.git"
    arka setup
    arka doctor
    ```
  </Tab>

  <Tab title="pip / venv">
    Install into an existing virtual environment or user site-packages.

    ```bash theme={null}
    python3 -m pip install "arka-agent[chat]"
    arka setup
    arka doctor
    ```

    GitHub fallback (no clone):

    ```bash theme={null}
    python3 -m pip install "arka-agent[chat] @ git+https://github.com/Sumit884-byte/arka.git"
    arka setup
    ```
  </Tab>

  <Tab title="Git clone (contributors)">
    Only needed if you are **developing Arka itself** or patching the repo.

    ```bash theme={null}
    git clone https://github.com/Sumit884-byte/arka.git
    cd arka
    ./scripts/refetch.sh --install
    arka setup
    ```
  </Tab>

  <Tab title="Editable dev">
    For contributors working inside the repo with live code changes.

    ```bash theme={null}
    git clone https://github.com/Sumit884-byte/arka.git && cd arka
    python3 scripts/sync_bundled.py
    pip install -e ".[chat]"
    arka setup
    ```
  </Tab>
</Tabs>

<Check>
  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.
</Check>

### Use Arka from any terminal

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

```bash theme={null}
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](https://fishshell.com):

```bash theme={null}
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

<Steps>
  <Step title="Configure API keys">
    Copy the example env file and add at least one provider key.

    ```bash theme={null}
    cp .env.example ~/.config/arka/.env
    ```

    Minimum `.env` for a quick start:

    ```env theme={null}
    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
    ```

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

  <Step title="Verify the install">
    Run diagnostics to confirm dependencies and API keys.

    ```bash theme={null}
    arka doctor
    ```
  </Step>

  <Step title="Run your first command">
    Ask a question and see Arka route it to the web answer skill.

    ```bash theme={null}
    arka ask "what is Rust?"
    ```

    Try a few more:

    ```bash theme={null}
    arka "convert 100 USD to INR"
    arka council "should I learn Rust?"
    arka quiz python
    arka route "convert 100 USD to INR"
    arka help
    ```
  </Step>

  <Step title="Personalize (optional)">
    Pick interests and get skill recommendations tailored to you.

    ```bash theme={null}
    arka personalize wizard
    arka personalize recommend
    ```

    See [Personalize your Arka experience](/guides/personalize) for interest tags and non-interactive flags.
  </Step>

  <Step title="Install fish shell (optional)">
    Fish unlocks the full 70+ skill router. The pip package ships `config.fish`.

    ```bash theme={null}
    # macOS
    brew install fish

    # Linux
    apt install fish

    # Windows
    scoop install fish
    ```
  </Step>
</Steps>

## Optional extras

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

```bash theme={null}
pip install "arka-agent[all]"
```

## Next steps

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

<CardGroup cols={2}>
  <Card title="How to code with Arka" icon="laptop-code" href="/guides/code-with-arka">
    Daily coding workflow — setup, edits, review, CI, and Cursor MCP.
  </Card>

  <Card title="CLI reference" icon="terminal" href="/guides/cli">
    All commands, aliases, and subcommands.
  </Card>

  <Card title="Skills catalog" icon="puzzle-piece" href="/guides/skills">
    What you can ask Arka to do.
  </Card>

  <Card title="How routing works" icon="route" href="/concepts/routing">
    Offline rules, LLM fallback, and correction layer.
  </Card>

  <Card title="LLM configuration" icon="brain" href="/concepts/llm">
    Providers, failover, and per-skill models.
  </Card>

  <Card title="Configuration" icon="gear" href="/reference/configuration">
    Env vars, precedence, and built-in defaults.
  </Card>

  <Card title="Voice" icon="microphone" href="/guides/voice">
    Wake word, STT, and TTS setup.
  </Card>

  <Card title="Arka Council" icon="users" href="/guides/council">
    Multi-persona deliberation.
  </Card>

  <Card title="Changelog" icon="newspaper" href="/changelog/2026-07-13">
    What's new this week.
  </Card>
</CardGroup>


## Related topics

- [Arka — AI terminal agent documentation](/index.md)
- [How to code with Arka](/guides/code-with-arka.md)
- [Personalize your Arka experience](/guides/personalize.md)
- [Skills catalog: 70+ built-in Arka commands](/guides/skills.md)
- [MCP integration for Cursor and Claude](/guides/mcp.md)