Once Cli Operator

When to Use

Primary skill for: ONCE CLI/TUI operations, lifecycle management, troubleshooting.

Use this skill when users ask things like:

• "how do I use once"
• "once cli commands"
• "once backup/restore"
• "once update"
• "once service not running"
• "troubleshoot ONCE app"

Explicit skill handoffs (use these exact phrases):

• For deployment orchestration: "For NAS deployment workflow, invoke nas-once-deployment skill."
• For app compatibility: "To check if this app is ONCE-ready, invoke once-readiness-evaluator skill."

Do not use this skill for:

• Deploying/hosting apps on NAS (invoke nas-once-deployment)
• Evaluating whether an app image is ONCE-compatible (invoke once-readiness-evaluator)
• Implementing or refactoring ONCE source code
• Editing host-wide infra files unrelated to ONCE operations

Operator Workflow

1. Confirm goal and risk level (read-only, routine change, destructive change).
2. Collect current state with inspection commands before changing anything.
3. Propose a concise command sequence with checkpoints.
4. Call out expected outputs and verification signals.
5. For destructive steps (remove/teardown/overwrite restore), require explicit user confirmation.
6. After execution, report outcomes with evidence and next recovery option.

Response Format

Always structure operational guidance as:

1. Current State Checks
2. Recommended Commands
3. What Success Looks Like
4. Recovery Path (if relevant)

Keep commands copy-paste ready and in execution order.

Command Guidance

Use the command catalog in references/command-map.md.

Default to this sequence for unknown systems:

1. once list
2. once version
3. Targeted app command (once start|stop|update|backup|restore|remove ...)

If ONCE service health is suspected, include background service checks and related commands.

TUI vs CLI

• Prefer TUI (once) for guided setup and interactive operations.
• Prefer CLI subcommands for repeatable, scripted, or incident-response operations.

Safety Rules

• Never present destructive operations as implicit defaults.
• Require explicit confirmation before suggesting execution of remove/teardown or overwrite-style restore actions.
• Avoid inventing outputs; state expected signals and ask user to confirm actual output.

Troubleshooting

Use references/troubleshooting.md symptom-to-action playbooks.

When troubleshooting:

1. Gather evidence first (state, command output, app reachability).
2. Isolate likely failing layer (service, container/app, hostname/TLS, backup/restore path).
3. Provide minimal correction commands.
4. Re-check with the same evidence command used before the change.

ONCE Contract Quick Reference

When discussing app compatibility during operations:

• HTTP on port 80
• Health endpoint at /up
• Persistent data under /storage (and /rails/storage for Rails compatibility)
• Optional hooks: /hooks/pre-backup, /hooks/post-restore

Canonical definition: See once-readiness-evaluator skill for full compatibility contract and scoring rubric.

Non-Goals

• This skill does not modify ONCE CLI internals.
• This skill does not replace deployment architecture design.

Examples

See references/examples.md for operator-ready command flows.