snapshot suggests an `update` command; one dropped flag from a write

[chuckmeyer]

Problem

cmd_snapshot ends with (cli.py:664):

print(f"\nVerify it round-trips: algolia-agent update {args.agent_id} --config {out_path} --dry-run")

The command as printed is read-only and the round-trip check it suggests is genuinely useful. The concern is what it is one edit away from: drop --dry-run — by trimming the line, by shell history editing, by a copy that clips at the newline — and the same command becomes a write against the agent that was just snapshotted.

That matters because snapshot is the natural first command to run against an agent you do not own or do not want to touch. Capturing a production agent in another application to study its configuration is exactly that case, and there the output actively suggests the one command class that must not run.

Suggested fix

Options, roughly in order of preference:

1. Print the hint only when the agent is safe to write to. There is no reliable signal for that, so in practice: suppress it for status: "published", or drop it entirely and document the round-trip check in the README instead (it is already documented under Snapshots).
2. Invert the emphasis so the read-only nature is not a trailing flag:

   Verify it round-trips (read-only):
     algolia-agent update <id> --config <path> --dry-run
   

   Weaker — the truncation risk is unchanged.
3. Add a --check alias for update --dry-run that has no writing form at all, and suggest that instead. Strongest, since no amount of trimming turns --check into a write. Costs a new subcommand or flag.

My preference is 3, falling back to 1 if a new surface is not wanted.

Related hardening worth considering separately

The same reasoning applies to update itself: there is currently no way to tell the CLI "this agent is read-only to me". Something like ALGOLIA_AGENT_READ_ONLY=1, or a --no-write global flag that makes any mutating call a hard error, would let someone point the CLI at a production application with a structural guarantee rather than care. Relevant because the credential precedence (--app-id/--api-key → env → .env) makes pointing at another application easy and unremarkable.

Context

Found while snapshotting a production agent in another application, read-only, to study its configuration. The snapshot itself is strictly read-only — cmd_snapshot makes exactly one get_agent call and no mutating call is reachable from it — so the tool behaved correctly. Only the closing hint is the problem.