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
poly init with no arguments. The CLI walks you through interactive dropdowns:
- Region — auto-selected if your API key only has access to one.
- Account — auto-selected if there’s only one in the region; otherwise pick from a searchable list.
- 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.
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
Runpoly --help to see every available command:
--help for its own flags and options:
Core commands
The ADK provides the following core commands:poly init
Initialize a new Agent Studio project locally.
poly pull
Pull the latest project configuration from Agent Studio.
poly push
Push local changes back to Agent Studio.
poly status
View changed, new, and deleted files in your project.
poly diff
Show differences between the local project and the remote version.
poly branch
Manage project branches.
poly format
Format project resources.
poly validate
Validate project configuration locally.
poly review
Create a GitHub gist for reviewing changes.
poly chat
Start an interactive chat session with your agent.
poly revert
Revert local changes.
Explore any command
To learn what a command does and what flags it accepts, run it with--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:
--force to override:
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:
poly push, merge the branch with poly branch merge (or publish it in Agent Studio), then chat against main instead. The CLI reaches main through the sandbox environment:
main publishes it to Live. Take this route only when the changes are ready for customers. Otherwise, test the Branch in Agent Studio with an in-app call or chat, which works in 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.CLI reference
See a more detailed overview of the available commands.
Build an agent
Follow the step-by-step workflow for using the ADK in practice.