For Coding Agents | ArchAstro Docs

Human? This page is written for the coding agent at your terminal. If you're looking for the human walkthrough, see Getting Started.

Overview

Connect the CLI to the user's existing app. If they do not have an app, ask them to create one in the developer portal first. Installing and signing in does not require creating an agent or deploying a sample.

Quick prompt

If the user hasn't pasted instructions yet, the canonical version is:

Help me connect the ArchAstro CLI to my app.

1) Ask for my app's name and ID. If I do not have an app, ask me to create
 one at https://developers.archastro.ai/dashboard/apps before continuing.

2) Install the CLI. macOS: brew install ArchAstro/tools/archastro.
 Linux/Windows: https://docs.archastro.ai/docs/start-here/cli.

3) Run archastro auth login and let me complete browser authorization.
 Run archastro auth status and verify the selected app matches the app
 I provided. Stop and ask me if it does not match.

4) Report whether the CLI is connected, then ask what I want to build.
 Do not create apps, agents, or other resources without my confirmation.
 Reference: https://docs.archastro.ai/llms-full.txt.

The CLI runs directly from your coding tool's terminal. No plugin installation, harness restart, or embed command is needed for this setup.

Where to find what

Resource	URL
Documentation	`https://docs.archastro.ai`
Developer Portal	`https://developers.archastro.ai`
LLM index (short)	`https://docs.archastro.ai/llms.txt`
LLM index (extended)	`https://docs.archastro.ai/llms-full.txt`

Treat these as canonical. Don't invent alternate hosts or endpoint roots.

Environment variables

Check for these before non-interactive operations. Ask the user if any are missing rather than guessing.

Variable	When you need it	Purpose
`ARCHASTRO_AUTH_HEADLESS`	CI or non-interactive use	Tells the CLI there is no browser; sign in with a profile created on a machine that has one
`ARCHASTRO_PROFILE`	More than one account or app on one machine	Selects which saved CLI profile to use

If the user wants to author an agent template by hand

Only author or deploy a template when the user asks to build an agent. Confirm the target app before writing resources.

kind: AgentTemplate
agent_key: support-agent
name: Support Agent
model: openrouter/anthropic/claude-sonnet-latest
identity: |
 You help users resolve support and billing
 problems with short, concrete answers.

tools:
 - tool_type: builtin
 builtin_tool_key: search
 status: active
 - tool_type: builtin
 builtin_tool_key: knowledge_search
 status: active

routines:
 - name: Respond in conversations
 handler_type: preset
 preset_name: participate
 event_type: thread.session.join
 event_config:
 thread.session.join: {}
 status: active

installations:
 - install_type: memory/long-term
 config: {}

Keep the model: field when authoring AgentTemplate YAML. Start with openrouter/anthropic/claude-sonnet-latest unless the user requests another provider; accepted formats are anthropic/<model>, openai/<model>, google/<model>, xai/<model>, meta/<model>, fireworks/<model>, vertex/<model>, and openrouter/<vendor>/<model>. Use archastro help models or archastro list aimodels before inventing a model string.

For everything else, see Agents and use archastro <verb> --help to discover flags.

Names you'll use in conversation

Term	What it means
Agent	The long-lived AI identity the user creates and manages
Routine	An event handler on an agent: when X happens, do Y
Automation	An event handler on the project (not tied to one agent)
Tool	An action the agent can take
Knowledge	Information the agent can retrieve
Thread	The conversation surface where people and agents exchange messages
Network	A shared space where agents from two companies can collaborate

Rules

Check required env vars before write operations. Ask for what's missing.
Setup ends after authentication is verified. Do not install a sample or create resources as an onboarding side effect.
Confirm the target app and requested changes before creating or deploying an agent.
Use archastro --help, archastro <verb> --help, and archastro help models to discover flags and model IDs. Don't guess.
Use llms-full.txt before scraping rendered pages.
Don't put secret keys in client-side code or commit them.
Don't add scaffolding the user didn't ask for.
When you're done, summarize the verified account and app, and any changes the user explicitly requested. Do not describe authentication alone as deploying an agent.