Explain required command environment, files, and env-variable priority for current city command groups

Command Environment Requirements

This page answers one question: what environment each studio command group needs to run correctly.

0) Top-level command boundary

Top-level command groups are:

studio console
studio agent
studio plugin

Commands like studio chat, studio task, studio memory, studio shell, studio skill, studio asr, and studio tts are plugin commands, not top-level roots.

1) Environment by command group

Command Group	Required Environment	Optional Environment	Notes
`studio init`	Writable `~/.downcity/`	None	Writes `~/.downcity/downcity.db`
`studio start/stop/restart/status`	Writable `~/.downcity/console/`	None	Manages global console process and registry
`studio console`	Console is running; browser can reach UI port	`--host`, `--port`	Single UI instance can switch across multiple running agents
`studio agent create`	Writable target directory	None	Generates `downcity.json`, `PROFILE.md`, `.downcity/`
`studio agent start`	Console is running; project has `downcity.json` + `PROFILE.md`	`--host`	Agent port is allocated by console and registered into console registry
`studio agent restart/status/doctor`	Target agent is registered in console registry	None	Operates through registry resolution
`studio config ...`	Valid `downcity.json` exists under target path	`--path`	Reads/writes project config; does not call agent API
`studio plugin list/status`	None	`--json`	Static plugin catalog; does not resolve any agent
`studio plugin start/stop/restart/command`	Target agent is running	`--agent`, `--path`, `--host`, `--port`	Used for managed plugins
`studio plugin action ...`	Project has `downcity.json`	`--path`	Advanced local execution form
`studio <managed-plugin> <action>`	Target agent is running	`--path`, `--host`, `--port`	Examples: `studio chat`, `studio task`, `studio memory`, `studio shell`
`studio <local-plugin> <action>`	Project has `downcity.json`	`--path`	Examples: `studio skill`, `studio web`, `studio asr`, `studio tts`

2) Runtime transport

Default rule:

no --host / --port: use the local agent daemon HTTP endpoint resolved from the target project
--host or --port provided: override the endpoint and use HTTP with the given host/port

Bearer-token resolution matters only when the target HTTP endpoint currently requires auth.

3) `DC_AUTH_TOKEN`

For most local usage, you do not need to care about auth env vars.

Managed-runtime calls default to the local daemon HTTP endpoint. DC_AUTH_TOKEN matters only when that HTTP endpoint requires auth.

Priority order:

explicit --token
DC_AUTH_TOKEN

4) Context env requirements for common commands

`studio chat ...`

If --chat-key is omitted, it tries DC_CTX_CHAT_KEY
If --session-id is omitted, it first tries DC_SESSION_ID

`studio task ...`

Task creation and run need sessionId
Pass --session-id explicitly, or rely on DC_SESSION_ID

5) Recommended usage

Use plugin roots for day-to-day work:

studio chat send --chat-key ctx_xxx --text "hi"
studio task list
studio memory search "release decision"
studio plugin list

Command Environment Requirements

Table of Contents