Repository navigation
docs(cli): document projects create + setup and dedup story - #4357
Conversation
- Update the `projects` section in the CLI reference to match the shipped `--clone`/`--import` flags and add the new `projects setup <id>` block. - Fix `projects list` shape (org-wide; columns NAME/SLUG/REPO/ID). - Update the host-server "Create or adopt a project" walkthrough to explain when to use `create` vs `setup` so users adopting a project on a fresh machine don't end up with a duplicate cloud row. - Tighten the "Local vs. remote hosts" section in getting-started to reflect that mutating host commands now require an explicit `--host` or `--local` (no default). - Drive-by: fix the `workspaces create` flag table to match.
📝 WalkthroughWalkthroughThis PR updates CLI documentation to reflect a new project model where projects are org-wide repositories with cloud records. Key changes include redesigning projects list for org-wide scope, introducing projects setup for adopting existing projects, and requiring explicit host targeting in mutating commands rather than defaulting to local. ChangesCLI Projects & Workspaces Documentation
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
Greptile SummaryThis PR updates the CLI documentation for the new
Confidence Score: 4/5Safe to merge after fixing the missing Two of the three files are consistent and correct. The third ( apps/docs/content/docs/cli/host-server.mdx — the "Create your first workspace" code block needs
|
| Filename | Overview |
|---|---|
| apps/docs/content/docs/cli/cli-reference.mdx | Adds projects setup command block, corrects projects list output shape and scope, renames --url/--path to --clone/--import, and makes --host/--local required on projects create and workspaces create; workspaces delete may have a stale "Defaults to local" description. |
| apps/docs/content/docs/cli/getting-started.mdx | Bootstrapping flow now covers projects create and projects setup before workspace creation; --local added to workspaces create example; "Local vs. remote hosts" clarifies mutating vs. read-only defaults correctly. |
| apps/docs/content/docs/cli/host-server.mdx | Dedup story (first-machine create vs. subsequent-machine setup) is well written, but the "Create your first workspace" example omits the now-required --local flag from workspaces create, which would produce a validation error for readers following the guide. |
Flowchart
%%{init: {'theme': 'neutral'}}%%
flowchart TD
A([User wants to use a project]) --> B[superset projects list]
B --> C{Project exists in org?}
C -- No --> D["superset projects create\n--name ... --local\n--clone URL --parent-dir ~/code\nOR --import ~/code/repo"]
C -- "Yes, not on this machine" --> E["superset projects setup ID\n--local --parent-dir ~/code\nOR --import ~/code/repo"]
C -- "Yes, already set up here" --> F([No-op / already ready])
D --> G["superset workspaces create\n--project prj_... --name ... --branch ... --local"]
E --> G
G --> H([Workspace ready])
Comments Outside Diff (2)
-
apps/docs/content/docs/cli/host-server.mdx, line 123-129 (link)The
workspaces createexample here is missing the now-required--local(or--host) flag. Per this PR's stated rule — and consistent with the updated examples ingetting-started.mdx(line 98-103) andcli-reference.mdx(line 506-511) — mutating host commands require an explicit--hostor--local. A reader following this guide would get a flag-validation error.bash
superset workspaces create
--project prj_…
--name "fix-login-bug"
--branch fix/login-bug
--localPrompt To Fix With AI
This is a comment left during a code review. Path: apps/docs/content/docs/cli/host-server.mdx Line: 123-129 Comment: The `workspaces create` example here is missing the now-required `--local` (or `--host`) flag. Per this PR's stated rule — and consistent with the updated examples in `getting-started.mdx` (line 98-103) and `cli-reference.mdx` (line 506-511) — mutating host commands require an explicit `--host` or `--local`. A reader following this guide would get a flag-validation error. bash superset workspaces create \ --project prj_… \ --name "fix-login-bug" \ --branch fix/login-bug \ --local ``` ``` How can I resolve this? If you propose a fix, please make it concise.
-
apps/docs/content/docs/cli/cli-reference.mdx, line 520-522 (link)workspaces deletestill says--hostdefaults to the local machine, but the PR establishes that mutating host commands require an explicit--hostor--local. Ifdeleteactually follows the new requirement, the description here is wrong; if it genuinely still defaults to local, a note in the "Local vs. remote hosts" prose saying which commands are exceptions would prevent confusion.Prompt To Fix With AI
This is a comment left during a code review. Path: apps/docs/content/docs/cli/cli-reference.mdx Line: 520-522 Comment: `workspaces delete` still says `--host` defaults to the local machine, but the PR establishes that mutating host commands require an explicit `--host` or `--local`. If `delete` actually follows the new requirement, the description here is wrong; if it genuinely still defaults to local, a note in the "Local vs. remote hosts" prose saying which commands are exceptions would prevent confusion. How can I resolve this? If you propose a fix, please make it concise.
Prompt To Fix All With AI
Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.
---
### Issue 1 of 2
apps/docs/content/docs/cli/host-server.mdx:123-129
The `workspaces create` example here is missing the now-required `--local` (or `--host`) flag. Per this PR's stated rule — and consistent with the updated examples in `getting-started.mdx` (line 98-103) and `cli-reference.mdx` (line 506-511) — mutating host commands require an explicit `--host` or `--local`. A reader following this guide would get a flag-validation error.
```suggestion
```bash
superset workspaces create \
--project prj_… \
--name "fix-login-bug" \
--branch fix/login-bug \
--local
```
```
### Issue 2 of 2
apps/docs/content/docs/cli/cli-reference.mdx:520-522
`workspaces delete` still says `--host` defaults to the local machine, but the PR establishes that mutating host commands require an explicit `--host` or `--local`. If `delete` actually follows the new requirement, the description here is wrong; if it genuinely still defaults to local, a note in the "Local vs. remote hosts" prose saying which commands are exceptions would prevent confusion.
```suggestion
{ flag: "--host <id>", description: "Target host machineId. Mutually exclusive with `--local`; one is required." },
{ flag: "--local", description: "Target this machine. Mutually exclusive with `--host`; one is required." },
]}
output={`{ deleted: string[] }`}
```
Reviews (1): Last reviewed commit: "docs(cli): document `projects create` + ..." | Re-trigger Greptile
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
apps/docs/content/docs/cli/host-server.mdx (1)
123-129:⚠️ Potential issue | 🔴 Critical | ⚡ Quick winMissing required
--hostor--localflag.The
workspaces createcommand is missing the required--hostor--localflag. According to the CLI reference (cli-reference.mdx lines 498-499), one of these flags is required (mutually exclusive).🔧 Proposed fix
superset projects list superset workspaces create \ --project prj_… \ --name "fix-login-bug" \ - --branch fix/login-bug + --branch fix/login-bug \ + --local🤖 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 `@apps/docs/content/docs/cli/host-server.mdx` around lines 123 - 129, The sample CLI invocation for superset's workspace creation is missing the required mutually exclusive flag; update the example showing "superset workspaces create" to include either the --host or the --local flag (e.g., add --host <HOST_URL> or --local) so it matches the CLI reference and the required options for the workspaces create command.
🧹 Nitpick comments (1)
apps/docs/content/docs/cli/cli-reference.mdx (1)
397-430: ⚡ Quick winClarify when
--parent-diror--importis required.The idempotency note (lines 420-421) explains that re-running
setupon an already-configured project is a no-op, but it's not explicitly stated whether--parent-dir(clone mode) or--import(import mode) is required for the initial setup. New users might be unsure whether they can runsetup <id> --localwithout specifying a mode.Consider adding a sentence like: "For initial setup, specify either
--parent-dirto clone the repo or--import <path>to register an existing checkout."🤖 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 `@apps/docs/content/docs/cli/cli-reference.mdx` around lines 397 - 430, Add a clarifying sentence to the "superset projects setup <id>" command description stating that for initial setup you must specify either --parent-dir to clone the repo or --import <path> to register an existing checkout (when using --local or remote host), and leave the existing idempotency note unchanged; update the prose near the idempotency lines that reference re-running to include this initial-setup requirement and mention the --parent-dir and --import flags by name so users know which mode to choose.
🤖 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 `@apps/docs/content/docs/cli/host-server.mdx`:
- Around line 123-129: The sample CLI invocation for superset's workspace
creation is missing the required mutually exclusive flag; update the example
showing "superset workspaces create" to include either the --host or the --local
flag (e.g., add --host <HOST_URL> or --local) so it matches the CLI reference
and the required options for the workspaces create command.
---
Nitpick comments:
In `@apps/docs/content/docs/cli/cli-reference.mdx`:
- Around line 397-430: Add a clarifying sentence to the "superset projects setup
<id>" command description stating that for initial setup you must specify either
--parent-dir to clone the repo or --import <path> to register an existing
checkout (when using --local or remote host), and leave the existing idempotency
note unchanged; update the prose near the idempotency lines that reference
re-running to include this initial-setup requirement and mention the
--parent-dir and --import flags by name so users know which mode to choose.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 422bce3f-8ee7-4c86-a343-b100c1a9d798
📒 Files selected for processing (3)
apps/docs/content/docs/cli/cli-reference.mdxapps/docs/content/docs/cli/getting-started.mdxapps/docs/content/docs/cli/host-server.mdx
🚀 Preview Deployment🔗 Preview Links
Preview updates automatically with new commits |
Summary
Updates the CLI docs for the new
projects create(#4355) andprojects setup(#4356) commands, plus a few drive-by corrections that were already wrong before this work.cli-reference.mdx—projectssectionprojects listwas documented as host-scoped withrepoOwner/repoName/repoPath. Actual command is org-wide returningname/slug/repoCloneUrl/id. Fixed.projects createflag list updated to the shipped surface:--clone <url>(was--url),--import <path>(was--path), and--host/--localare now required (one of).projects setup <id>block documenting the dedup-aware adoption path.host-server.mdx— Create or adopt a projectRewrote the walkthrough so the dedup story is explicit: first machine runs
create; subsequent machines runsetup <id>to attach to the existing cloud project instead of duplicating it. Updated all flag examples.getting-started.mdxcreateor attach viasetup.projects create,projects setup,workspaces create) require explicit--host/--local; read-only host queries default to local.Drive-by
workspaces createflag table also said--hostdefaults to local — it doesn't. Fixed alongside.Test plan
bun run lintcleanbun run buildinapps/docssucceeds/cli/cli-reference,/cli/getting-started,/cli/host-serverpages on Vercel previewSummary by cubic
Adds docs for
projects createand the newprojects setup, and clarifies the create-vs-setup flow so teams don’t create duplicate cloud projects. Also fixesprojects listoutput and host-targeting flags across the CLI docs.New Features
projects setup <id>to adopt existing cloud projects on a new machine (clone/import modes, idempotent, no--cloneneeded).projects createto the shipped surface:--clone,--import, and required--hostor--local; add concise examples.createvssetup.Bug Fixes
projects list: org-wide scope, columnsNAME/SLUG/REPO/ID, and output shape.workspaces createtable and host-targeting docs: mutating commands require explicit--hostor--local; read-only lists default to local.Written for commit 85004a2. Summary will update on new commits.
Summary by CodeRabbit
projectsandworkspacescommands with refined options and output formats.projects setupcommand for adopting existing projects on new hosts.--hostor--localselection for mutating commands).