# CLI reference

## Commands

| Command                    | What it does                                                      |
| -------------------------- | ----------------------------------------------------------------- |
| `stackai`                  | Start an interactive chat session (keeps context across messages) |
| `stackai "<prompt>"`       | Run the agent once on the current directory, then exit            |
| `stackai login`            | Log in — prompts for your API key (masked)                        |
| `stackai login <key>`      | Log in directly with a key                                        |
| `stackai logout`           | Remove your saved API key                                         |
| `stackai whoami`           | Show the current user + today's usage                             |
| `stackai --help`           | Show all commands                                                 |
| `stackai --version`        | Print the version                                                 |
| `stackai auth <key> <url>` | Advanced: save a key with a custom API URL                        |

## What the agent can do

Inside a run, the agent has these tools:

| Tool                                     | Purpose                                         |
| ---------------------------------------- | ----------------------------------------------- |
| `read_file` / `write_file` / `edit_file` | Read and modify files                           |
| `list_files` / `create_dir`              | Explore and create folders                      |
| `search_files`                           | Regex content search across the project (grep)  |
| `find_files`                             | Find files by glob pattern (e.g. `src/**/*.ts`) |

It works **only inside your current directory** and shows each action live (`● Write(file)`, `● Edit(file)`, …) with a diff preview.

## Config

Your key is saved to `~/.stackai/config.json`. Override the API URL per-machine with the `STACKAI_API_URL` environment variable.

{% hint style="warning" %}
Each step the agent takes counts as **one request** against your daily limit. A complex multi-file task can use several.
{% endhint %}

{% hint style="info" %}
Interactive mode needs a **real terminal (TTY)**. In a piped or non-TTY shell, use a one-shot instead: `stackai "your prompt"`.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.usestackai.com/cli/cli-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.