CLI Command Reference

What You Will Learn

• Understand canonical command identifiers and CLI argument shape.
• Discover commands with predictable search patterns.
• Inspect command schemas before execution.
• Route execution by HTTP method and safety guarantees.

Canonical Command Identifiers

Oatty resolves commands in canonical `<group> <command>` form.

Use canonical identifiers when inspecting or running commands to avoid ambiguity.

Treat canonical IDs as stable references for scripts and workflow steps.

# General pattern
oatty <group> <command> [flags]

# Example
oatty apps apps:list --project-id proj_123

expected Canonical IDs remain consistent across discovery and execution paths.

recovery If you only have vendor CLI syntax, run command search first and copy the canonical ID from results.

Command Discovery

Use search first when you do not know the exact command path.

Keep search terms short and task-oriented, then narrow with specific nouns.

After selecting a candidate, inspect schema before execution.

# Fuzzy discovery
oatty search "project domain"

# Narrow intent
oatty search "projects list"

# Review root help for available command groups
oatty --help

tip Prefer discovery output over memorized commands when catalogs change.

advanced For repeated automation, validate once in TUI/CLI, then pin the exact command line in scripts.

Schema Inspection and Input Review

Review command details before sending requests to production systems.

Confirm required positional arguments, required flags, and payload shape.

Use help output to compare expected input names with your script variables.

# Inspect one command in detail
oatty help apps apps:create

# Alternate: contextual help during TUI command selection
# press F1 in Run Command

expected Help output should identify required and optional command inputs.

recovery If execution fails due to missing inputs, map each error field to the corresponding required flag or positional argument.

Execution Routing and Safety Model

Execution mode follows command backing type and HTTP method.

Read-only requests are routed through safe execution paths.

Mutating requests are routed through non-destructive or destructive paths depending on method.

# Read-only (HTTP GET)
run_safe_command

# Non-destructive write (HTTP POST/PUT/PATCH)
run_command

# Destructive write (HTTP DELETE)
run_destructive_command

tip Use preview/inspection before destructive operations.

advanced In workflows, keep destructive steps isolated and clearly labeled for easier review and rollback planning.

Automation Patterns

Use CLI mode for deterministic non-interactive runs in CI/CD or scheduled jobs.

Keep inputs explicit and environment-driven where possible.

Capture stdout/stderr in your job logs for auditability and failure triage.

# Script-friendly command
oatty workflow run deploy --input env=staging

# Standard shell guard pattern
set -euo pipefail
oatty search "apps list"

fallback When TUI discovery identifies the right command, copy that exact command into scripts instead of rewriting it from memory.

recovery If CI runs behave differently, verify catalog availability, headers, and environment variables in the job context.