Write command names as plain text in CLI output

[schnie]

What

The CLI's own messages named commands, flags and paths the way the docs do, in backticks: "astro dev start was removed in Astro CLI v2. Use astro local start instead." A terminal printed the backticks literally, and so did the --output json error object. This PR writes them as plain text at the source:

astro dev start was removed in Astro CLI v2. Use astro local start instead.

There is no runtime transform. The PR's first commit (a renderer that bolded or stripped backticks at output time) is reverted in the second. Review found it unsafe in four ways:

• a % inside a span went through aurora's Sprintf;
• it stripped real backticks from uv, HTTP and Airflow text that passes through;
• it rewrote copy-paste commands;
• it missed notes inside json payloads.

Plain text at the source has none of those problems.

What changed

• 217 string literals in 84 non-test Go files now carry no backticks. They cover errors, warnings, notes (astro init conversion notes, check notes, Deployment clone notes, the astro dev stub's payload error and notes), help Short/Long/flag usage, next steps (astro package), prompts, and removed-command and removed-flag messages. This spans cmd/, internal/, airflow/, and the pkg/* sub-modules awsauth, checks, container, emfetch, googleauth, imagebuild, instancelocate, instances, localrt and scaffold, plus pkg/httputil and pkg/util. Astro Desktop sees the plain text too, since it imports the sub-modules.
• Wording is otherwise unchanged. Where a bare command read ambiguously mid-sentence, the sentence was minimally rephrased instead of quoted:
  • "set creates …" became "The set command creates …" in four places (env, deployment and link removal guidance);
  • "ls lists" became "The ls command lists" (local api), and "list shows" became "The list command shows" (variables);
  • "use astro local start --docker then" became "then use astro local start --docker" (dev stub note);
  • "Drop the local" became "Drop local from the command";
  • "run uv run pytest yourself" became "run your tests yourself with uv run pytest";
  • "mark a link default = true" became "set default = true on a link";
  • "add a line .env" became "add a .env line";
  • "link narrows … use get" became "linking narrows … use the get command";
  • "Check workspace and domain in pyproject.toml" became "Check the workspace and domain keys in pyproject.toml", with the same change for "sets no workspace" and "organization and workspace under [tool.astro]";
  • the MWAA region hint became "check this link's environment and the region under …";
  • "with dockerfile under [tool.astro]" became "with the dockerfile key under [tool.astro]";
  • the if r.Format == FormatJSON panic text became "branch on r.Format == FormatJSON";
  • the astro init note that lists several astro link add … commands now joins them with "; " rather than ", ", so one command is not read as running into the next.
• The Otto upgrade prompt's "bring Airflow up" clause from the CLI (cliUpgradePrompt.BringUp) is now plain, matching what Astro Desktop already sends.
• The rest of the prompt (pkg/scaffold/airflowupgradeprompt.go) stays markdown.
• Not touched: Go raw-string delimiters, comments, docs (docs/*.md are markdown), and text passed through from uv, Airflow or an API.

Guard tests

• TestMessagesWriteCommandsAsPlainText (internal/archlint/backticks_test.go) parses every non-test .go file in the repo, sub-modules included. It fails on any string literal that holds a backtick, and the failure message states the convention. It skips e2e/, *.gen.go, testdata/ and the test-helper packages cliouttest/ and instancestest/. Its allowlist, backtickAllowed, has three entries:

  • pkg/scaffold/templates.go: the README and AGENTS.md that astro init writes into a project, which are markdown;
  • pkg/scaffold/airflowupgradeprompt.go: the prompt handed to Otto, which is markdown for a model and is never printed;
  • pkg/scaffold/files1x.go, the literal "$*?\"`: the shell metacharacters that make an argument unsafe to repeat unquoted.

  An entry that no longer matches anything also fails the test.

• TestHelpHasNoBackticks (cmd/help_backticks_test.go) renders every help page in every tree from rootsUnderTest, hidden commands included. It fails on any line with a backtick, which also catches strings assembled at run time.

• docs/architecture.md: a new "Commands in messages" section under Output states the convention and the two guards, and the help style guide gains a bullet for it.

• Tests that pinned backticked text were updated in 52 test files, including e2e/devstub_test.go and e2e/convert_test.go.

• make update-schemas changed no goldens; they pin shapes, not values.

#2291 (removed-commands-and-bundle-output)

git merge-tree --write-tree HEAD origin/removed-commands-and-bundle-output conflicts in 6 files. Both PRs edit the same removed-command message lines, and #2291 also restructures the stubs around them:

• cmd/astro/deployment_removed.go
• cmd/astro/env_removed.go
• cmd/astro/env_var_link.go
• cmd/local/dev.go
• cmd/local/run_removed.go
• cmd/removed_flags_test.go

To resolve, take #2291's structure (cliout.RemovedCommand / removedCmdStub) and its wording ("was removed in Astro CLI v2", "It has no replacement in the CLI yet: …"), with the backticks dropped. Whichever PR merges second must then update these strings from #2291:

• head in deployment_removed.go and env_removed.go, and the env_var_link.go guidance: "astro deployment %s was removed in Astro CLI v2." becomes "astro deployment %s was removed in Astro CLI v2."
• the Shorts: "Removed in v2 — use set, which creates or updates" becomes "… use the set command, which creates or updates"; "Removed in v2 — local Airflow lives under astro local", "Removed in v2 — use "+replaceRunDag+"" and "Removed in v2 — use astro env " + o.envNoun + "" lose their backticks;
• the t.Skip text in removed_flags_test.go is a conflict on wording only.

It must also update these #2291 tests:

• cmd/removed_commands_test.go: namesReplacement looks for "`astro " in the guidance. Plain guidance ("Use astro local start instead") needs "astro " or "Use astro ".
• cmd/local tests asserting "Use astro local status instead" (and similar) need the plain form.
• TestMessagesWriteCommandsAsPlainText and TestHelpHasNoBackticks fail on any backticked string left in, so a missed one cannot slip through.

Checks

• go build ./... and GOOS=windows go build ./... pass.
• GOOS=windows go vet ./cmd/... passes.
• make test and make test-submodules pass.
• make test-e2e (tier 0) passes.
• make lint passes; the only follow-up was a gofmt comment-alignment fix, committed separately.
• make lint-submodules, make lint-e2e, make lint-goos and make deadcode pass.
• make update-schemas produced no diff.

Breaking changes

The text of messages changes. A script that greps stderr, or an error object's error, for a backticked command (`astro local start`) now sees astro local start. The JSON shapes are unchanged.

[coveralls-official]

Coverage Report for CI Build 37986622376

Coverage increased (+0.003%) to 57.678%

Details

• Coverage increased (+0.003%) from the base build.
• Patch coverage: 10 uncovered changes across 6 files (113 of 123 lines covered, 91.87%).
• No coverage regressions found.

Uncovered Changes

File	Changed	Covered	%
internal/instancelocate/instancelocate.go	4	1	25.0%
cmd/local/runs_wait.go	7	5	71.43%
cmd/otto.go	2	0	0.0%
cmd/link_pickers.go	2	1	50.0%
cmd/local/local.go	4	3	75.0%
internal/platform/astro/deploy/deploy.go	2	1	50.0%
Total (53 files)	123	113	91.87%

Coverage Regressions

No coverage regressions found.

---

Coverage Stats

Relevant Lines:	69458
Covered Lines:	40062
Line Coverage:	57.68%
Coverage Strength:	252.34 hits per line

---

💛 - Coveralls