> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poly.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# First commands
Once the ADK is installed and your API key is set, the very first thing to do is create a local project with `poly init`. After that, the fastest way to get oriented is to inspect the CLI directly from inside that project folder.
## Create your local project with `poly init`
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly init
```
Run `poly init` with no arguments. The CLI walks you through interactive dropdowns:
1. **Region** — auto-selected if your API key only has access to one.
2. **Account** — auto-selected if there's only one in the region; otherwise pick from a searchable list.
3. **Project** — pick from a searchable list of every project the API key can see.
`poly init` then creates a subdirectory at `{account_id}/{project_id}` in your current directory and pulls the project configuration down from Agent Studio. When it completes, `cd` into that folder — every other `poly` command runs from inside the project directory.
**Skip the prompts if you already know the IDs**
For scripting or repeat runs, pass any combination of flags to skip the matching prompts:
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly init --account_id --project_id
poly init --region --account_id --project_id
```
The IDs appear in the Agent Studio URL when your project is open:
```
https://studio.poly.ai///...
```
`poly init --json` requires all three flags (no interactive prompts in JSON mode).
If the project has already been initialized locally at a previous point, use `poly pull` to refresh it in place instead of running `poly init` again.
## View top-level help
Run `poly --help` to see every available command:
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly --help
```
Each command also accepts `--help` for its own flags and options:
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly push --help
```
## Core commands
The ADK provides the following core commands:
Initialize a new Agent Studio project locally.
Pull the latest project configuration from Agent Studio.
Push local changes back to Agent Studio.
View changed, new, and deleted files in your project.
Show differences between the local project and the remote version.
Manage project branches.
Format project resources.
Validate project configuration locally.
Create a GitHub gist for reviewing changes.
Start an interactive chat session with your agent.
Revert local changes.
## Explore any command
To learn what a command does and what flags it accepts, run it with `--help`:
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly init --help
poly pull --help
poly push --help
```
## Common first-run behavior
### `poly status` shows variables you didn't create
After `poly init` or `poly pull`, `poly status` may report `variables/` entries as new files — for example, `variables/caller_number` or `variables/verified_record`. These are **virtual**: the ADK scans function code for `conv.state.*` assignments and tracks each one as a variable resource. No corresponding files exist on disk. This is expected and does not mean you have changes to push.
### `poly status` shows platform-generated functions as modified
After a fresh `poly init` or `poly pull`, `poly status` may report functions such as `functions/get_api_keys.py` or `functions/check_otp.py` as modified, even though you have not touched them. The diff is typically a single stripped blank line introduced by the platform. These are harmless — the ADK and the platform have slightly different whitespace conventions for generated code. You can push through them or ignore them.
### `poly branch switch` reports uncommitted changes
If `poly status` shows phantom `variables/` entries or modified platform functions and you try to switch branches, the ADK may block the switch:
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Cannot switch branches with uncommitted changes. Use --force to switch and discard changes.
```
Use `--force` to override:
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly branch switch --force
```
This does not lose any real work — the `variables/` entries are virtual and will reappear after the next pull.
### `poly chat` returns a 404 on a feature branch
`poly chat` defaults to chatting against your current branch's last pushed state. On most projects this works fine; on some projects the branch deployment endpoint returns a 404:
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Error: 404 ... /branches//sequence
```
If you hit this, push your changes with [`poly push`](/adk/reference/cli#poly-push), merge the branch with [`poly branch merge`](/adk/reference/branch_merge) (or in the Agent Studio UI), then chat against sandbox instead:
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly chat --environment sandbox
```
### `poly branch delete` fails with a 404 or requires a TTY
`poly branch delete` triggers the same platform endpoint as branch chat. If the endpoint is unavailable, the delete will fail with a 404 after the confirmation prompt. Additionally, running `poly branch delete` in a non-interactive environment (for example, from a script) throws `[Errno 22] Invalid argument` because the command requires a terminal for its confirmation prompt.
If you are stuck with a branch you cannot delete from the CLI, delete it through the Agent Studio UI instead.
## Next step
Continue to the command reference for a complete listing, or go straight to the tutorial to see a real workflow.
See a more detailed overview of the available commands.
Follow the step-by-step workflow for using the ADK in practice.