docs: add Codacy Analysis CLI page under Codacy CLIs

[claudiacodacy]

What

Adds a reference page for the Codacy Analysis CLI (@codacy/analysis-cli, the codacy-analysis command) at docs/codacy-analysis-cli/index.md, registered in the nav under Codacy CLIs beside the Codacy Cloud CLI.

The CLI had no page of its own. Its install and init steps lived inside the Codacy Guardrails getting-started page, and five other pages linked to that anchor (#install-cli) or to npm. This gives it a home and repoints those references.

Why the page says what it says

Every command, flag, and environment variable is checked against CLI 0.23.0 — codacy-analysis <command> --help, codacy-analysis info, and the README from the package tarball (the npm web page carries none). Four behaviors that neither the help output nor the README states correctly were found by running the CLI, and the page documents the verified behavior:

Claim	Verified behavior
Exit codes	0 no issues, 1 issues found, 2 invalid flag combination. There is no "execution error" code: an unavailable tool, even with --fail-if-missing, still exits 0 — so --fail-if-missing does not fail a CI job.
--inspect / --install-dependencies	A three-way mutual exclusion with --fail-if-missing. The README documents only the two-way conflict.
exclude_paths	analyze reads the exclude list recorded in codacy.config.json, never .codacy.yaml directly. Editing .codacy.yaml changes nothing until init or update-config runs (2 issues → 1 issue only after update-config).
config --merge	Keeps the destination's metadata.source, so merging a --remote config into an --auto one stays source: auto and update-config remains incremental afterwards (tools +0/-0).

Also verified rather than assumed: Node.js ≥ 20; every environment variable named on the page exists in the package; init writes codacy.config.baseline.json and a .codacy/.gitignore; init modes and the --staged/--diff/--pr flags are mutually exclusive; a git flag combined with --files is an intersection; tool IDs PyLintPython3, Semgrep (Opengrep), ESLint9; SARIF output is real SARIF; and the shared-credentials claim (the Cloud CLI authenticated with no token on the command line and none in the environment, reading the same ~/.codacy/credentials).

Not exercised, and resting on --help plus the README, which agree: upload and init --remote against a live repository token.

Highlighted workflow

A Common workflows section leads with combining init --auto with the repository's Codacy Cloud config, since neither set contains the other:

codacy-analysis init --auto
codacy-analysis init --remote gh my-org my-repo --config-file .codacy/remote.json
codacy-analysis config --merge --source .codacy/remote.json

--intersect is presented as the same move in reverse, for when a merge surfaces more than you want to act on. The measured pattern counts are deliberately not baked into the page — that config changes — so it shows the CLI's own output line instead.

Deliberate choices

• Links the npm package, not the source repository — codacy/analysis-cli is private and would 404 for readers.
• No table of tool IDs. The page names the two traps (PyLintPython3, Semgrep) and points at codacy-analysis info; a 30-row inventory would rot.
• ## Use the CLI in CI stays top-level rather than nesting under Common workflows, so it keeps its place in the "On this page" nav (toc_depth: 2).

Left alone

Three pages say "Codacy Analysis CLI" but mean the legacy codacy-analysis-cli (the Scala/Docker tool). Repointing them would change a factual claim, not a link, so they're untouched and worth a separate pass:

• docs/repositories-configure/codacy-configuration-file.md:75 — validate-configuration, a command the new CLI does not have
• docs/faq/troubleshooting/why-is-my-file-over-150-kb-missing.md:13
• docs/faq/troubleshooting/why-arent-duplication-metrics-being-calculated.md:33

Verification

• mkdocs build --strict passes apart from one expected warning: git-revision-date-localized has no git log for the new file, which resolves once this is merged. Anchors are validated (validation.anchors: warn), so the internal cross-links resolve.
• nav: entry checked by hand. No redirect needed — the page is new, nothing moved.
• vale docs/codacy-analysis-cli/index.md — 10 advisory errors, all the same classes the existing Codacy Cloud CLI page produces: spaced em dashes (repo-wide convention), endraw from the Jinja block, lowercase codacy/auto-and inside anchor ids, and misconfigured missing from the vocabulary.

🤖 Generated with Claude Code

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

AI Reviewer: first review requested successfully. AI can make mistakes. Always validate suggestions.

_{TIP This summary will be updated as you push new changes.}

[codacy-production]

Pull Request Overview

The CI example should not be merged as written because it uses an undocumented CODACY_PROJECT_TOKEN variable without passing --repository-token, which may cause authentication failures for init --remote and upload. Codacy reports the PR as up to standards, with no quality issues detected.

About this PR

• The documented CLI behaviors are not covered by automated tests or reproducible validation fixtures, leaving authentication and edge-case documentation vulnerable to regression.

Test suggestions

• Validate that the new CLI page is registered in navigation and all intended cross-links resolve.
• Verify the documented installation, authentication, and environment-variable instructions.
• Verify init modes and the --staged/--diff/--pr mutual exclusions.
• Verify analyze exit codes and the three-way conflict among --inspect, --install-dependencies, and --fail-if-missing.
• Verify exclude_paths are consumed from codacy.config.json and require init or update-config after source changes.
• Verify config --merge preserves destination metadata.source and remains compatible with incremental update-config.
• Verify the CI workflow uses a token variable and upload invocation accepted by the Analysis CLI.

Prompt proposal for missing tests

Consider implementing these tests if applicable:
1. Validate that the new CLI page is registered in navigation and all intended cross-links resolve.
2. Verify the documented installation, authentication, and environment-variable instructions.
3. Verify init modes and the `--staged`/`--diff`/`--pr` mutual exclusions.
4. Verify analyze exit codes and the three-way conflict among `--inspect`, `--install-dependencies`, and `--fail-if-missing`.
5. Verify `exclude_paths` are consumed from `codacy.config.json` and require init or update-config after source changes.
6. Verify `config --merge` preserves destination `metadata.source` and remains compatible with incremental update-config.
7. Verify the CI workflow uses a token variable and upload invocation accepted by the Analysis CLI.

_{TIP Improve review quality by adding custom instructions
TIP How was this review? Give us feedback}

[claudiacodacy]

Restructured in 2053d39 after review feedback that the section layout was incoherent — it was a command-by-command body with a Common workflows section bolted on the end.

13 top-level sections → 10. The old ones ranged from 4 to 90 lines, so the "On this page" nav was a flat list of equal-looking entries for things that were not equal. For comparison, the sibling Codacy Cloud CLI page has 6 and nests its capabilities as ### under one ##.

What changed:

• Requirements now carries the path to a first analysis, branching on the one question that decides it — whether the repository is on Codacy. Previously that path sat in section 10 of 13, behind nine sections of reference.
• init leads with a recommendation instead of a flat five-way menu of modes with no default: init --remote when the repository is on Codacy, init --auto when it isn't, then the two narrower modes.
• Common workflows keeps only the recipes that compose commands the body can't show individually — the --auto plus Codacy Cloud merge, and CI. The other three restated the command sections and are gone, absorbed into Requirements and Scope the analysis.
• Merged Inspect your stack with Combine configuration files, and Codacy Self-hosted with Run behind a proxy.

Nothing was dropped and no new claims were introduced: every command, environment variable, and verified behavior from the first commit is still on the page, checked by diffing the command and term sets between revisions. All five explicit anchors are unchanged, including #authentication, which docs/codacy-skills/index.md links to — that's the only inbound anchor anywhere in docs/.

mkdocs build --strict is now fully clean; the git-revision-date-localized warning from the first commit was only the file being uncommitted, as expected.

[github-actions]

Overall readability score: 54.01 (🟢 +0.05)

File	Readability
running-eslint.md	67.53 (🟢 +0)
client-side-tools.md	43.43 (🟢 +0)
index.md	66.84 (🟢 +0.01)
codacy-guardrails-troubleshooting.md	48.96 (🟢 +0)
codacy-guardrails-getting-started.md	59.25 (🟢 +0.61)
codacy-guardrails-faq.md	60.94 (🟢 +0)
index.md	60.96 (🟢 +0)
index.md	67.67 (-)

View detailed metrics

🟢 - Shows an increase in readability
🔴 - Shows a decrease in readability

File	Readability	FRE	GF	ARI	CLI	DCRS
running-eslint.md	67.53	52.7	9.13	10.8	9.69	7.11
	🟢 +0	🟢 +0	🟢 +0	🟢 +0	🟢 +0	🟢 +0
client-side-tools.md	43.43	32.33	12.83	15.2	13.11	8.1
	🟢 +0	🟢 +0	🟢 +0	🟢 +0	🟢 +0	🟢 +0
index.md	66.84	49.31	8.5	10.1	11.48	7.02
	🟢 +0.01	🔴 -0.1	🔴 -0.02	🟢 +0	🟢 +0	🟢 +0.02
codacy-guardrails-troubleshooting.md	48.96	41.9	13.38	12.9	11.37	8.38
	🟢 +0	🟢 +0	🟢 +0	🟢 +0	🟢 +0	🟢 +0
codacy-guardrails-getting-started.md	59.25	49.04	11.25	13.4	10.79	6.71
	🟢 +0.61	🟢 +0.2	🟢 +0.07	🟢 +0	🟢 +0.3	🟢 +0.01
codacy-guardrails-faq.md	60.94	48.09	10.44	10.2	11.19	7.84
	🟢 +0	🟢 +0	🟢 +0	🟢 +0	🟢 +0	🟢 +0
index.md	60.96	40.65	9.65	10.8	12.06	7.22
	🟢 +0	🟢 +0	🟢 +0	🟢 +0	🟢 +0	🟢 +0
index.md	67.67	52.49	9.88	10.8	9.98	6.53
	-	-	-	-	-	-

Averages:

	Readability	FRE	GF	ARI	CLI	DCRS
Average	54.01	42.96	10.93	12.36	12.29	8.01
	🟢 +0.05	🟢 +0.04	🟢 +0	🟢 +0.01	🟢 +0.01	🟢 +0.01

View metric targets

Metric	Range	Ideal score
Flesch Reading Ease	100 (very easy read) to 0 (extremely difficult read)	60
Gunning Fog	6 (very easy read) to 17 (extremely difficult read)	8 or less
Auto. Read. Index	6 (very easy read) to 14 (extremely difficult read)	8 or less
Coleman Liau Index	6 (very easy read) to 17 (extremely difficult read)	8 or less
Dale-Chall Readability	4.9 (very easy read) to 9.9 (extremely difficult read)	6.9 or less