| name | agentuity-ops |
| description | When running Agentuity CLI commands for deploying, managing databases, creating sandboxes, configuring storage, queues, cron jobs, email, or any cloud resource. Also activates for SSH debugging, environment variables, and non-interactive automation. |
| version | 2.0.0 |
Agentuity CLI & Operations Reference
CLI Accuracy Contract (NON-NEGOTIABLE)
- Never guess flags, subcommands, or argument order
- If not 100% certain, FIRST run:
agentuity <cmd> --help
- Trust CLI output over memory — never fabricate URLs or outputs
- For the full CLI schema:
agentuity ai schema show
Key Conventions
- Agentuity projects always use
bun (never npm/pnpm) — check for agentuity.json or .agentuity/
- Check region config before adding
--region flags (~/.config/agentuity/config.json and agentuity.json)
- Sandbox default working directory is
/home/agentuity (not /app)
- Always read actual command output for URLs — never fabricate them
Non-Interactive Execution
When running CLI commands programmatically (in Claude Code, CI, or scripts), skip confirmation prompts:
| Flag | Short | Behavior |
|---|
--confirm | -y | Skip confirmation prompts |
--force | — | Alias for --confirm (when command doesn't have its own --force) |
These work on any command with a confirmation prompt (deploy, create, delete, etc.).
Special cases:
agentuity project import — requires BOTH --name and -y (or --confirm) for non-interactive useagentuity cloud env push — has its own --force flag (overwrites remote values); --force does NOT alias --confirm hereagentuity cloud deployment remove/undeploy — has its own --force flag for the same reason
Golden Commands
| Purpose | Command |
|---|
| Create project | agentuity create |
| Start dev server | agentuity dev or bun run dev |
| Deploy | agentuity deploy |
| Check auth | agentuity auth whoami |
| List regions | agentuity region list |
| Get help | agentuity <command> --help |
| Full CLI schema | agentuity ai schema show |
| Migrate to v2 | npx @agentuity/migrate |
Cloud Services
Documentation Links
Common Mistakes
| Mistake | Better Approach | Why |
|---|
Blindly adding --region flag | Check config first | Region may already be configured |
| Using npm for Agentuity projects | Always use bun | Agentuity is Bun-native |
Hardcoding sandbox paths as /app | Use /home/agentuity | That's the default working directory |
| Making up CLI flags | Run --help first | Flags change between versions |
| Fabricating deployment URLs | Read actual output | URLs are generated dynamically |
Using expect/yes piping for prompts | Use -y or --confirm flag | Built-in flag support is cleaner and more reliable |
| Running v1 project without migrating | Run npx @agentuity/migrate first | v2 requires explicit agent/router wiring |
When In Doubt, Check the Docs
If you're unsure about any CLI command, flag, or service, check first rather than guessing:
