Skip to content

docs: update violet command reference#765

Open
jiazhiguang wants to merge 1 commit intomasterfrom
docs/violet
Open

docs: update violet command reference#765
jiazhiguang wants to merge 1 commit intomasterfrom
docs/violet

Conversation

@jiazhiguang
Copy link
Copy Markdown
Contributor

@jiazhiguang jiazhiguang commented May 9, 2026

Document the current violet list and gc behavior and correct push flags so upgrade guidance matches the CLI implementation.

Summary by CodeRabbit

  • Documentation
    • Updated violet CLI documentation with new platform-token authentication method.
    • Added documentation for violet list command features including installed app exports and cluster filtering.
    • Extended violet push command documentation with new optional flags for advanced deployment control.
    • Improved security guidance recommending token-based authentication over password-based methods.

Review Change Stack

@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai Bot commented May 9, 2026

Warning

Rate limit exceeded

@jiazhiguang has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 41 minutes and 44 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 14c140bf-8c6a-49d1-87bb-81c7299695fb

📥 Commits

Reviewing files that changed from the base of the PR and between e818711 and 15c2217.

📒 Files selected for processing (1)
  • docs/en/extend/upload_package.mdx

Walkthrough

This PR updates violet CLI documentation across two files to reflect new authentication mechanisms, expanded command functionality, and improved security guidance. Key changes include adding token-based authentication parameters, substantially expanding the violet list command documentation for app export workflows, and extending violet push with new optional flags.

Changes

Violet CLI Documentation Updates

Layer / File(s) Summary
Authentication & Common Parameters
docs/en/extend/upload_package.mdx
Added --platform-token token-based authentication and --client-id OAuth parameter to common platform connection parameters, noting that --platform-token is incompatible with username/password credentials.
violet list Command Expansion
docs/en/extend/upload_package.mdx
Expanded documentation to explain exporting installed applications to YAML files for Marketplace extension downloads. Added details on app type mappings, default output behavior (apps.yaml or stdout), optional cluster filtering, and token authentication examples. Removed outdated "list all plugins uploaded" description.
violet push Command Flags
docs/en/extend/upload_package.mdx
Added four new optional flags: --target-catalog-source, --target-chartrepo, --skip-crs, and --skip-push. Documented mutual exclusion constraint that --skip-crs and --skip-push cannot be used together.
Security Guidance
docs/en/upgrade/pre-upgrade.mdx
Updated pre-upgrade warning to recommend using --platform-token instead of --platform-password to prevent credential exposure in shell history and process listings.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

  • alauda/acp-docs#180: Modifies the same violet push/upload workflows and introduces the same flags (--skip-crs, --skip-push).
  • alauda/acp-docs#708: Updates the same pre-upgrade authentication guidance for violet list, recommending token-based methods over passwords.
  • alauda/acp-docs#455: Expands the same violet list command documentation with optional flags and authentication options.

Suggested reviewers

  • chinameok

Poem

🐰 A token hops where passwords fled,
Violet commands in docs, brightly fed.
List apps to YAML, push without pause,
Security shines through the Rabbit's cause! 🌟

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'docs: update violet command reference' directly reflects the main changes, which are comprehensive updates to the violet CLI documentation covering list, push, and upgrade guidance.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/violet

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

  • Generate code and open pull requests
  • Plan features and break down work
  • Investigate incidents and troubleshoot customer tickets together
  • Automate recurring tasks and respond to alerts with triggers
  • Summarize progress and report instantly

Built for teams:

  • Shared memory across your entire org—no repeating context
  • Per-thread sandboxes to safely plan and execute work
  • Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started


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

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
docs/en/upgrade/pre-upgrade.mdx (1)

52-58: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Inconsistent password exposure guidance.

The violet push example uses --platform-password on the command line, but there's no warning about password exposure in shell history and process listings (unlike the violet list example at lines 40-44). The same security concern applies to both commands.

Consider adding a similar warning or updating the example to use --platform-token for consistency.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/en/upgrade/pre-upgrade.mdx` around lines 52 - 58, The example for the
violet push command exposes credentials via --platform-password; update the
example to either use --platform-token instead of --platform-password (and show
a placeholder like "<platform_token>") or add the same security warning present
for violet list about avoiding passwords on the command line and preferring
tokens or environment variables; change the command snippet (referencing the
violet push invocation and the --platform-password flag) and add one short
warning sentence directly below the snippet mentioning shell
history/process-list exposure and recommending --platform-token or env var
usage.
🧹 Nitpick comments (1)
docs/en/extend/upload_package.mdx (1)

136-142: 💤 Low value

Verify "L4/L5 applications" terminology is clear to users.

Line 136 refers to "L4/L5 applications" but then immediately explains them as ModulePlugin, OperatorBundle, and Chart types. If "L4/L5" is internal or unfamiliar jargon, consider using the concrete type names directly or adding a brief explanation of what L4/L5 means in this context.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/en/extend/upload_package.mdx` around lines 136 - 142, Replace or clarify
the ambiguous "L4/L5 applications" phrase in the docs around the `violet list`
usage by either removing the L4/L5 shorthand and referring directly to the
concrete types (ModulePlugin, OperatorBundle, Chart) or by adding a one-line
parenthetical explaining what L4/L5 denotes (e.g., which deployment/extension
layer or internal classification) so readers immediately understand the mapping
between "L4/L5" and the listed types; update the sentence that currently starts
with "When upgrading the platform, use `violet list` to list the L4/L5
applications..." to use the chosen clearer wording.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@docs/en/upgrade/pre-upgrade.mdx`:
- Around line 52-58: The example for the violet push command exposes credentials
via --platform-password; update the example to either use --platform-token
instead of --platform-password (and show a placeholder like "<platform_token>")
or add the same security warning present for violet list about avoiding
passwords on the command line and preferring tokens or environment variables;
change the command snippet (referencing the violet push invocation and the
--platform-password flag) and add one short warning sentence directly below the
snippet mentioning shell history/process-list exposure and recommending
--platform-token or env var usage.

---

Nitpick comments:
In `@docs/en/extend/upload_package.mdx`:
- Around line 136-142: Replace or clarify the ambiguous "L4/L5 applications"
phrase in the docs around the `violet list` usage by either removing the L4/L5
shorthand and referring directly to the concrete types (ModulePlugin,
OperatorBundle, Chart) or by adding a one-line parenthetical explaining what
L4/L5 denotes (e.g., which deployment/extension layer or internal
classification) so readers immediately understand the mapping between "L4/L5"
and the listed types; update the sentence that currently starts with "When
upgrading the platform, use `violet list` to list the L4/L5 applications..." to
use the chosen clearer wording.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: dee0e2ad-12b8-481b-ba89-32dcf2eb73ac

📥 Commits

Reviewing files that changed from the base of the PR and between 63ccc65 and e818711.

📒 Files selected for processing (2)
  • docs/en/extend/upload_package.mdx
  • docs/en/upgrade/pre-upgrade.mdx

Document the current violet list and gc behavior and correct push flags so upgrade guidance matches the CLI implementation.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@cloudflare-workers-and-pages
Copy link
Copy Markdown

cloudflare-workers-and-pages Bot commented May 9, 2026

Deploying alauda-container-platform with  Cloudflare Pages  Cloudflare Pages

Latest commit: 15c2217
Status: ✅  Deploy successful!
Preview URL: https://94267030.alauda-container-platform.pages.dev
Branch Preview URL: https://docs-violet.alauda-container-platform.pages.dev

View logs

@chinameok
Copy link
Copy Markdown
Contributor

Review on the violet command reference update. Findings split into P1 (in-scope inconsistency), P2 (structural / AI-usability), P3 (nits), plus a cross-doc follow-up. Author to judge what to act on.

P1 — violet push examples are out of sync with the new auth recommendation in the same file

violet list and violet gc now show --platform-token as the recommended secure auth method (lines 158, 166, 217, 225, 233). But every violet push example in the same file still uses only --platform-username + --platform-password (lines ~335, 348, 367, 381, 396).

A reader scanning the file will reasonably assume violet push does not support --platform-token, or that the token recommendation is somehow specific to read commands. CodeRabbit flagged the same shape in pre-upgrade.mdx's push example — same root cause.

Either:

  • add a --platform-token example next to each violet push snippet, or
  • add one paragraph at the top of ### violet push:

    For non-interactive use, prefer --platform-token over --platform-password. See Common Parameters.

P2 — "L4/L5 / L3/L4 applications" is internal jargon; the user-facing term is Aligned / Agnostic

Two locations:

  • line ~136 (violet list intro):

    use violet list to list the L4/L5 applications installed in the current environment …

  • line ~196 (violet gc intro):

    clean up uninstalled L3/L4 Operator and ClusterPlugin resources …

The user-facing life-cycle vocabulary in this repo is Core / Aligned / Agnostic, defined in overview/architecture.mdx#L80-L83 and used in overview/release_notes.mdx#L37-L39. This PR's own line 140 already correctly says:

ModulePlugin — cluster plugins whose lifecycle type is aligned or agnostic.

So the file uses two vocabularies four lines apart.

Suggested rewording:

  • violet list intro → use \violet list` to list the installed extensions with `Aligned` or `Agnostic` life cycle and export the result to a YAML file.Add one short sentence:`Core` plugins follow the cluster upgrade and are not managed through `violet list`.` That fact matters during upgrade planning.
  • violet gc intro → clean up uninstalled Operator and Cluster Plugin resources whose life cycle is \Aligned` or `Agnostic`.`

P2 — Document recommends --platform-token but never says how to obtain one

The reader is told to substitute <platform_token> with a real value, but the file does not say where the token comes from, who can create it, or how lifecycle / expiration / rotation works. AI-usable docs guidance: critical field values need a documented source.

There is already an authoritative procedure in this repo. apis/overview/intro.mdx ### Obtaining an <Term name="productShort" /> User Token walks through Profile → API Tokens → Add API Token. The kubeconfig how-to (configure/clusters/how-to/access-cluster-with-kubeconfig.mdx#L52) already references it from a Prerequisites section in the same idiom.

Suggest adding one sentence right after the --platform-token line in ### Common Parameters:

To create or manage platform tokens, sign in to the platform Web Console, open Profile > API Tokens, and create a token with an appropriate expiration. For details, see Obtaining a User Token.

That keeps the canonical procedure in one place and avoids duplicating the steps.

P2 — violet gc is destructive but the section has zero warning

violet gc deletes Artifact, ArtifactVersion, ModulePlugin, and ModuleConfig resources from the global cluster. The current section walks straight from a one-paragraph description into a ready-to-run delete command. There is no mention of --dry-run, no mention of confirmation, no mention of recovery.

Two options depending on what violet actually supports:

A. If violet gc has a --dry-run (or equivalent) flag:

  • list it under Optional Flags
  • reword the first paragraph so the recommended path is "dry-run first, then run for real"

B. If there is no dry-run today, add a :::danger admonition at the top of the section:

violet gc permanently deletes resources from the global cluster. Run during a documented maintenance window only. There is no undo.

Either way, the doc should not lead a reader to run a delete command without a stated safety mechanism.

P2 — violet gc opening paragraph mixes three naming systems

Same paragraph uses, in order:

  1. L3/L4 Operator and ClusterPlugin — internal layer prefix
  2. OperatorView and ModulePluginView records — internal CRD names
  3. Artifact, ArtifactVersion, ModulePlugin, ModuleConfig — the actually-deleted types

A reader cannot map these onto each other. Suggest restructuring the section as three layers:

  1. What it does (user view) — uninstalled Aligned / Agnostic operators and cluster plugins are cleaned up
  2. What it deletes — list the four resource types
  3. How it decides — checks OperatorView / ModulePluginView records (this can move to a short closing note or a collapsed details block, since it is more useful for engineers than for ops)

P3 — --client-id description is incomplete

Line ~93:

--client-id <OAuth client ID>  # OAuth client ID for username/password login (default: "alauda-auth")

A reader cannot tell whether --client-id is needed when using --platform-token, or whether the default alauda-auth should ever be overridden. Suggest:

Only used together with --platform-username/--platform-password; ignored when --platform-token is set. The default alauda-auth matches the platform's built-in OAuth client; override only if your platform was configured with a different client ID.

P3 — violet gc Optional Flags introduces a fourth verb

Body of the section uses "clean up", "GC", and "delete". The flag help text introduces a new word:

--clusters <cluster names>  # Recycle resources in the specified clusters, separated by commas

Switch to one of the existing verbs. Suggested:

# Limit cleanup to the specified clusters, separated by commas

P3 — violet push flag descriptions: custom and public-charts are ambiguous

In the Optional Flags block:

--target-catalog-source <catalog source>  # Specify target CatalogSource for operators: platform, system, or custom (default: "platform")
--target-chartrepo <chart repository>     # Specify target chart repository for Helm charts (default: "public-charts")

platform and system are literal values; custom reads as one too — but it is actually a placeholder meaning "any custom name". Likewise, public-charts could be a literal default or a stand-in. Suggest:

  • # Target CatalogSource for operators: \platform`, `system`, or a custom CatalogSource name (default: `platform`).Optionally add an example invocation--target-catalog-source my-catalog`.
  • # Target chart repository for Helm charts (default: \public-charts`, the platform-managed Helm repo provisioned by ACP).`

P3 — Optional Flags column alignment drift

In the new violet push Optional Flags block, the new lines --target-catalog-source and --target-chartrepo use one extra space before # compared to existing rows like --clusters. Code blocks do not render alignment, but the raw source is the human contract. Suggest pulling the comment column back to match the existing rows.

Cross-doc follow-up (out of scope for this PR)

The recently merged master:docs/en/upgrade/pre-upgrade.mdx shows the password-only violet list example with a vague stdin/env-var warning — written before --platform-token was documented. With this PR, that vague guidance is now stale. Recommend a follow-up PR that:

  • replaces the violet list example in pre-upgrade.mdx with a --platform-token version
  • adds a --platform-token example next to the TopoLVM violet push block (CodeRabbit flagged this one inline)
  • removes the "if your environment supports stdin/env var" sentence, since the actual answer is now --platform-token

Confirmed-good notes

  • \{#violet_gc_usage} anchor matches the existing \{#violet_list_usage} style ✅
  • --platform-token mutual exclusion with username/password is stated explicitly ✅
  • violet list default behavior (writes to stdout and apps.yaml) is called out — easy gotcha to miss otherwise ✅
  • Example outputs use realistic values, not synthetic placeholders ✅
  • --skip-crs / --skip-push mutual exclusion is documented ✅
  • violet gc scan scope ("all clusters visible to the platform user") makes the safety boundary clear ✅

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants