TerminalUse
Build, deploy, interact with agents. Flow: init → deploy → create task → send messages.
Full docs: https://docs.terminaluse.com/llms-full.txt
Default Rule For New Agents
When creating a new agent, use tu init by default.
Only skip tu init if the user explicitly instructs another approach (for example, modifying an existing agent template or a pre-scaffolded repository).
CLI Setup
The tu CLI is provided by the terminaluse Python package. Before running any tu commands:
- Verify
tuis available:which tu || echo "tu CLI not found" - If not installed, ask user whether they would like to install it or if there's a venv they would like to source
- Ensure you have auth configured:
- Interactive/local: tu login then tu whoami - Non-interactive/automation: set TERMINALUSE_API_KEY (and optionally TERMINALUSE_BASE_URL)
Context Requirement
Agent-scoped commands often default to config.yaml in the current directory when --agent/--config is omitted.
Before running agent-scoped commands without explicit flags:
ls config.yaml || echo "Not in agent directory"Use explicit flags when possible:
--agent <namespace/name>to avoid directory coupling--config <path>when working with a specific manifest
Quick Reference
| Action | Command | ||
|---|---|---|---|
| Login | tu login, tu whoami | ||
| Init agent | tu init (creates agent directory, no need to mkdir first) | ||
| Deploy | tu deploy -y | ||
| List deployments | tu ls | ||
| Rollback | tu rollback | ||
| List filesystems | tu fs ls | ||
| List projects | tu projects ls | ||
| Add env var | `tu env add <KEY> -v <val> -e prod\ | preview\ | all [--secret]` |
| Import env file | tu env import <file> -e <env> [--secret KEY] | ||
| Create task | tu tasks create --filesystem-id <fs-id> -m "message" [--json] | ||
| Create task (auto-create fs) | tu tasks create -p <project-id> -m "message" [--json] | ||
| Send message | tu tasks send <task-id> -m "message" [--json] | ||
| List tasks | tu tasks ls [--json] | ||
| Get task details | tu tasks get <task-id> |
tu fs is the canonical filesystems command. tu filesystems is a supported alias. tu tasks ls <id> is deprecated for single-task retrieval; use tu tasks get <id>. Prefer --json for CI/automation and agent-to-agent interaction.
Workflows
| Task | Reference |
|---|---|
| Create or edit an agent | ./workflows/create.md |
| Deploy to platform | ./workflows/deploy.md |
| Test/interact with agent | ./workflows/interact.md |
You must look at the corresponding workflow files based on user intent.
Anti-patterns
- Creating task without filesystem or project. Tasks either need a filesystem. If project is provided, a filesystem is auto-created in the project
- Modifying Dockerfile
ENTRYPOINT/CMD→ breaks deployment - Trying to use the agent right after updating secrets. You must wait for the new version to become active. Check with
tu ls
Error Recovery
| Error | Action |
|---|---|
| Deploy fails | tu ls <branch> lists deployments events for branch → find FAILED → fix → redeploy |
| Need rollback | tu rollback |
Docs/Skills Feedback
If docs or skills are wrong/unclear, ask user permission to send feedback to (include the feedback in the user request): Never include any sensitive information.
curl -X POST 'https://uutzjuuimuclittwbvef.supabase.co/functions/v1/tu-docs-feedback' \
-H 'Content-Type: application/json' \
-d '{"feedback":"<issue>", "page":"<page URL> or section name"}'