arctl run

Run the agent or MCP server defined by the declarative YAML in the project directory (defaults to “.”).

For Agents the default is to start the runtime in the background, wait until the agent’s HTTP endpoint is reachable, then launch an interactive A2A chat. When chat exits the runtime is torn down. Use –no-chat to keep the old foreground-only behavior.

For MCPServer kinds chat does not apply; the framework’s run command runs in the foreground until interrupted. Pass –inspector to launch the MCP Inspector subprocess (requires ’npx’ on PATH) alongside the server; the Inspector retries until the server is reachable.

Reads arctl.yaml to look up the matching framework by (framework, language) and dispatches to its run command. Loads .env (if present) and validates that the framework’s required env vars are set.

Usage

arctl run [DIRECTORY] [flags]

Example:

arctl run
arctl run ./myagent
arctl run -e FOO=bar -e BAZ=qux
arctl run --no-chat              # agent without chat
arctl run --watch                # iterative dev loop
arctl run mymcp --inspector      # MCP with MCP Inspector launched

Command-specific flags

--dry-run: Skip actual exec; useful for tests.
-e, --env stringArray: KEY=VALUE env override.
--inspector: Launch MCP Inspector alongside the server; it connects when ready (MCP projects only; errors on agent projects).
--no-chat: Skip chat for Agents; run the framework command in the foreground (agent projects only; errors on MCP projects).
--watch: Rebuild and restart on file change (skips chat for agents; for chat open a second terminal).

Global flags

-h, --help: Display help information for the command.
--registry-token string: Registry bearer token (defaults to value of ARCTL_API_TOKEN env var).
--registry-url string: Registry URL (overrides ARCTL_API_BASE_URL env var; defaults to http://localhost:12121).

arctl pull arctl runtime