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

# Arka CLI command and flag reference

> Reference for the arka command-line interface, including primary commands, the agent alias, subcommands, and flags for terminal usage.

The `arka` command is the main entry point. `agent` is an alias for the same router.

## Install the CLI (no build from source)

You do not need to clone the repo to use `arka` from your terminal. Install the **`arka-agent`** package:

```bash theme={null}
# Recommended — isolated CLI on PATH
pipx install "arka-agent[chat]"
arka setup
arka doctor

# PyPI not available yet? Install from GitHub without cloning:
pipx install "arka-agent[chat] @ git+https://github.com/Sumit884-byte/arka.git"
```

Then open a new terminal and run `arka help`. Only clone the repo if you are [contributing to Arka](https://github.com/Sumit884-byte/arka) or need editable installs (`pip install -e ".[chat]"`).

<Note>
  Config and cache live outside the install directory — typically `~/.config/arka/` (Linux), `~/Library/Application Support/arka/` (macOS), or `%APPDATA%\arka\` (Windows). Upgrading with `pipx upgrade arka-agent` keeps your keys and learned routes.
</Note>

## Primary commands

| Command                  | Description                              |
| ------------------------ | ---------------------------------------- |
| `arka <request>`         | Route natural language to the best skill |
| `agent <request>`        | Same router (alias)                      |
| `arka ask <question>`    | Web + AI answer                          |
| `arka route <request>`   | Preview routing without executing        |
| `arka goal <goal>`       | Autonomous multi-step agent loop         |
| `arka setup`             | Seed config dirs and dependencies        |
| `arka doctor`            | Install diagnostics                      |
| `arka reload`            | Re-read `.env` and `config.fish`         |
| `arka refetch --install` | Git pull + sync + reinstall              |
| `arka help`              | Skill overview                           |

## Developer tools

| Command                                 | Description                                                      |
| --------------------------------------- | ---------------------------------------------------------------- |
| `arka ci`                               | Run the local CI gate mirrored from GitHub Actions               |
| `arka ci --full`                        | Run the fast gate plus the full pytest suite                     |
| `arka ci --fix`                         | Run CI, then hand the first failure to the goal agent            |
| `arka review --staged`                  | Review staged changes with project-rule and test-gap hints       |
| `arka review`                           | Review the current diff vs the default base branch               |
| `arka route audit`                      | Compare symbolic routes, fish hooks, and NL coverage tests       |
| `arka skill new my_tool --template dev` | Scaffold a new plugin skill with manifest, runner, and docs stub |

Natural language examples:

```bash theme={null}
arka ci
arka ci --full
babysit this pr
check repo health
review staged
review vs main
route audit
skill new my_tool --template dev
```

## YouTube commands

See the full [YouTube guide](/guides/youtube).

| Command                         | Description                         |
| ------------------------------- | ----------------------------------- |
| `arka youtube research <query>` | Search + transcript research digest |
| `arka download <id-or-url>`     | Download video, Shorts, or playlist |
| `arka summarize youtube <id>`   | Summarize video or playlist         |
| `youtube_download <url>`        | Single video download (fish)        |
| `youtube_bulk download <url>`   | Bulk playlist/channel download      |

## Stock commands

See the full [Stock intelligence guide](/guides/stocks).

| Command                               | Description              |
| ------------------------------------- | ------------------------ |
| `stock news`                          | Market news feeds        |
| `stock prices [TICKER…]`              | Live prices              |
| `stock analyze TICKER`                | AI backtest + ML signal  |
| `stock fundamentals TICKER…`          | Ratios vs peers          |
| `stock invest <question>`             | Deep investment research |
| `predictions --domain stocks <topic>` | Opportunity analysis     |

## Voice and services

| Command                       | Description                                                              |
| ----------------------------- | ------------------------------------------------------------------------ |
| `arka listen`                 | Wake-word listener ("hey arka, …")                                       |
| `arka start` / `arka stop`    | Background services                                                      |
| `arka serve`                  | Remote server for phone STT/TTS                                          |
| `arka backend status`         | Check a local or hosted Arka backend                                     |
| `arka backend ask "<prompt>"` | Call `/v1/agent` directly from the terminal                              |
| `arka backend media <file>`   | Upload media to `/v1/media`                                              |
| `arka site_summary <url>`     | Summarize a bounded whole-site crawl while skipping social/offsite links |
| `arka speak-lang hi-IN`       | Set voice language                                                       |
| `arka reload --listen`        | Reload config and restart listener                                       |

Use `ARKA_BACKEND_URL` plus `ARKA_BACKEND_TOKEN` or `REMOTE_TOKEN` for hosted
backends:

```bash theme={null}
export ARKA_BACKEND_URL="https://your-arka.up.railway.app"
export ARKA_BACKEND_TOKEN="$REMOTE_TOKEN"
arka backend ask "init https://github.com/org/repo as a workspace"
```

Whole-site summary examples:

```bash theme={null}
arka site_summary https://example.com --max-pages 12 --depth 1
arka "summarize entire site https://example.com"
```

`site_summary` follows same-site links only and skips common social platforms
such as X/Twitter, LinkedIn, Instagram, YouTube, Reddit, Discord, and TikTok.

## LLM management

| Command                                  | Description                                            |
| ---------------------------------------- | ------------------------------------------------------ |
| `arka ai-models`                         | List providers and default models                      |
| `arka ai-skill-model`                    | Per-skill model configuration                          |
| `arka ai-skill-model profiles`           | Task profiles (route, chat, summarize)                 |
| `arka orchestrate --benchmark <request>` | Route using live benchmark winners for the routed task |
| `select_model`                           | Hardware-based model recommendations                   |
| `select_model --apply`                   | Apply recommendations to skill profiles                |

See [Hardware-aware model selection](/guides/select-model).

## Route learning

| Command                                            | Description                    |
| -------------------------------------------------- | ------------------------------ |
| `route_learn learn <phrase> <skill>`               | Teach a phrase → skill mapping |
| `route_learn learn --from-trace --correct <skill>` | Fix last routing mistake       |
| `route_learn list`                                 | List learned routes            |
| `route_learn delete <id>`                          | Remove a learned route         |
| `route_learn test <phrase>`                        | Preview routing for a phrase   |

See [Teaching custom routes](/guides/route-learn).

## Competitions

| Command                                       | Description                           |
| --------------------------------------------- | ------------------------------------- |
| `competitions sources`                        | List hackathon/ML competition sources |
| `competitions search <topic>`                 | Search all sources                    |
| `competitions search <topic> --source kaggle` | Search one platform                   |

See [Hackathons and ML competitions](/guides/competitions).

## Daily brief

| Command       | Description                         |
| ------------- | ----------------------------------- |
| `daily_brief` | Personalized morning tech headlines |

Natural language: `arka daily brief`, `arka morning tech brief`. See [Daily and tech brief](/guides/daily-brief).

## Gemini CLI

| Command                | Description                   |
| ---------------------- | ----------------------------- |
| `arka gemini`          | Interactive Google Gemini CLI |
| `arka gemini <prompt>` | One-shot prompt               |
| `arka gemini status`   | Install and auth check        |

See [Google Gemini CLI integration](/guides/gemini-cli).

## Social & media

| Command                    | Description                           |
| -------------------------- | ------------------------------------- |
| `post_x <url>`             | Fetch, shorten, and post to X/Twitter |
| `ascii_art <text>`         | Render ASCII art banner               |
| `ascii_art --image <path>` | Convert image to ASCII                |

## Google Workspace

| Command                        | Description                   |
| ------------------------------ | ----------------------------- |
| `arka google setup`            | Configure Google OAuth        |
| `arka google login`            | Authenticate Gmail + Calendar |
| `arka google gmail --unread`   | Fetch unread emails           |
| `arka google calendar --today` | Today's calendar events       |

## Plugins

| Command                     | Description            |
| --------------------------- | ---------------------- |
| `arka skills list`          | List installed plugins |
| `arka skills install <url>` | Install from git URL   |
| `arka skills refresh`       | Reload plugin registry |

## Council and deliberation

Full guide: [Arka Council](/guides/council)

| Skill          | Example                                   |
| -------------- | ----------------------------------------- |
| `council`      | `arka council "should I learn Rust?"`     |
| `council`      | `ask the council about switching careers` |
| `council list` | `arka council list`                       |

## Learning

Full guide: [Quiz practice](/guides/quiz-practice)

| Skill                | Example                         |
| -------------------- | ------------------------------- |
| `quiz_practice`      | `arka quiz python`              |
| `quiz_practice`      | `practice quiz biology mitosis` |
| `quiz_practice list` | `arka quiz_practice list`       |

## Goal agent

Run autonomous multi-step tasks with a step budget:

```bash theme={null}
arka goal set up a venv, install requests, and run pytest
arka goal -y -n 30 debug why nginx fails
```

Default step budget: `GOAL_MAX_STEPS=25`.

## Self-improve

Analyze and improve the Arka codebase:

```bash theme={null}
arka self improve
arka self improve routing --apply
arka self memory
```

If you want Arka to route a phrase, send it through `arka` first. Plain shell commands are not intercepted automatically.

See [Self-improve loop](/guides/self-improve).

## Operation modes

```bash theme={null}
arka mode debug    # show routing and LLM traces
arka mode agent    # default clean output
arka mode list
```

See [Operation modes](/guides/operation-modes).

## Provider selection

```bash theme={null}
arka provider list
arka provider show
arka provider set gemini
arka provider set openrouter --refresh
```

## Fish shell helpers

When using fish, these functions are available:

```fish theme={null}
agent_route "play bohemian rhapsody"   # preview routing
agent_trace                            # last routing decision
agent_why                              # explain skill choice
```

## Apply config changes

```bash theme={null}
arka reload              # re-read .env + config.fish
arka reload --listen     # also restart wake listener
```


## Related topics

- [Arka — AI terminal agent documentation](/index.md)
- [Skills catalog: 70+ built-in Arka commands](/guides/skills.md)
- [MCP integration for Cursor and Claude](/guides/mcp.md)
- [Quickstart: install Arka and run your first command](/quickstart.md)
- [Command aliases, subcommand synonyms, and skill names](/reference/aliases.md)