[omattsson]

Summary

Adds stackctl agent-guide, a Markdown guide for AI agents and scripts that is built into the binary. While writing the guide, three behaviours turned up that would mislead an agent or a script. This PR fixes them.

New: stackctl agent-guide

• Prints cli/cmd/agent_guide.md (embedded with go:embed; {{VERSION}} becomes the build version). It works without a config, like version.
• The guide covers: machine-readable output, -q, exit codes, authentication without a prompt, confirmations, --dry-run limits, waiting for long-running operations, errors, and common tasks.
• stackctl --help points to it; the README has a section "Use with AI agents and scripts".
• TestAgentGuide_CommandsExist checks every stackctl … invocation in the guide against the command tree: subcommands, flags and the number of positional arguments.

Fixes

• A declined confirmation exits 1 (was: Aborted. on stdout, exit 0). The message is now aborted: not confirmed, nothing changed on stderr. confirmAction returns errAborted itself, which removes 17 copies of the check.
• --follow after a normal server close (code 1000, for example a restart): it reads the instance. A final status counts as before; otherwise it exits 1 and says that the operation continues on the server (was: exit 0).
• stdout holds only data with -o json, -o yaml and -q. Printer.MachineReadable() sends PrintMessage text to Printer.ErrWriter (stderr). The table format and custom formats are unchanged.
  • stack deploy, stop, clean and rollback print the 202 response (log_id, message) with -o json|yaml and the log ID with -q (printOperation).
  • With --follow in those modes, the log goes to stderr and stdout gets the instance after the operation (-q: the log ID). stack logs -f prints the log as it does without --follow.
  • cluster shared-values list and config list print [] for an empty list.
• Refactor: config-free commands are marked with an annotation (skipsConfig) instead of matched by name.

Behaviour changes for scripts

• A declined prompt now exits 1 (was 0).
• With -o json, -o yaml or -q, messages such as Deleted stack …, --dry-run text and Aborted. moved from stdout to stderr.
• stack deploy|stop|clean -o json|yaml print JSON or YAML instead of a text line.
• --follow with -o json|yaml|-q writes the log to stderr instead of stdout.

Not changed (documented in the guide)

• bulk commands exit 0 even when some items fail (check failed in -o json).
• Ctrl-C during --follow exits 0.

Test plan

• make test: all packages pass, including e2e and integration
• make lint (go vet, staticcheck)
• New tests: guide drift (verified it catches a wrong subcommand, flag and argument count), output modes of deploy/stop/clean/rollback, --follow -o json|yaml|-q, stack logs -f -o json, --dry-run in json and quiet mode, empty lists as [], normal close during --follow, the e2e exit code of a declined prompt, MachineReadable, skipsConfig
• Ran the built binary: agent-guide with a missing config; stack delete --dry-run -o json (stdout empty, message on stderr)

🤖 Generated with Claude Code

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

Run configuration

• Source mode: Auto
• Repository: omattsson/stackctl
• Branch: feat/agent-guide
• File: .coderabbit.yaml
• Commit: 772df3a
• Layers: Repository YAML
• Review profile: CHILL
• Plan: Advanced
• Run ID: c19b72b1-e7ab-4acd-a472-3c9b3ff104cd

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}