updates for latest cmd changes

skarim · skarim · commit 3c30dae7eda3 · 2026-04-03T15:44:14.000-04:00
diff --git a/docs/src/content/docs/faq.md b/docs/src/content/docs/faq.md
@@ -24,26 +24,24 @@ gh stack add auth-layer
 # ... make commits ...
 gh stack add api-routes
 # ... make commits ...
-gh stack push
+gh stack submit
 ```
 
 Or you can create stacked PRs manually by setting each PR's base branch to the branch of the PR below it.
 
 ### How do I add PRs to my stack?
 
-Use `gh stack add <branch-name>` to add a new branch on top of the current stack. When you run `gh stack push`, a PR is created for each branch.
+Use `gh stack add <branch-name>` to add a new branch on top of the current stack. When you run `gh stack submit`, a PR is created for each branch and they are linked together as a Stack on GitHub.
 
 ### How can I modify my stack?
 
 Reordering or inserting branches into the middle of a stack is not currently supported. To restructure a stack, you need to delete it and recreate it with the desired order.
 
 ### How do I delete my stack?
 
-Use `gh stack unstack` to remove a stack from both local tracking and GitHub, or `gh stack unstack --local` to only remove the local tracking entry.
+<!-- TODO: Update once stack deletion workflow is finalized -->
 
-### What happens when you unstack?
-
-When you unstack, the local tracking metadata is removed. The branches and PRs on GitHub remain as-is unless you explicitly delete them. Note that auto-merge is disabled on any PR in a stack to avoid changes from one PR getting merged into another out of order.
+You can unstack a stacked of PRs from the PRs UI on the web. Functionality to do this from the CLI will be coming soon.
 
 ### Can stacks be created across forks?
 
diff --git a/docs/src/content/docs/getting-started/quick-start.md b/docs/src/content/docs/getting-started/quick-start.md
@@ -59,17 +59,25 @@ git add .
 git commit -m "Add API routes"
 ```
 
-### 4. Push and create PRs
+### 4. Push branches
 
-Push all branches and create pull requests in one command:
+Push all branches to the remote:
 
 ```sh
 gh stack push
 ```
 
-Each PR is created with the correct base branch — `auth-middleware` targets `main`, and `api-routes` targets `auth-middleware` — so reviewers see only the diff for that layer.
+### 5. Create PRs
 
-### 5. View the stack
+Create pull requests and link them as a stack on GitHub:
+
+```sh
+gh stack submit
+```
+
+Each PR is created with the correct base branch — your first branch targets `main`, and `api-routes` targets the first branch — so reviewers see only the diff for that layer. The PRs are automatically linked together as a Stack on GitHub.
+
+### 6. View the stack
 
 See the full state of your stack at any time:
 
diff --git a/docs/src/content/docs/guides/using-prs.md b/docs/src/content/docs/guides/using-prs.md
@@ -84,11 +84,14 @@ When you merge a PR at the bottom of the stack, the remaining branches are **aut
 After making local changes or resolving conflicts, use the CLI to push and sync:
 
 ```sh
-# Push all branches and create/update PRs
+# Push all branches to the remote
 gh stack push
 
+# Create or update PRs and the Stack on GitHub
+gh stack submit
+
 # Or sync everything in one command (fetch, rebase, push, update PRs)
 gh stack sync
 ```
 
-`gh stack push` uses `--force-with-lease` by default to safely update rebased branches.
+`gh stack push` uses `--force-with-lease` to safely update rebased branches. Use `gh stack submit` when you need to create new PRs or update the Stack on GitHub.
diff --git a/docs/src/content/docs/guides/workflows.md b/docs/src/content/docs/guides/workflows.md
@@ -20,8 +20,8 @@ gh stack init
 gh stack add api-routes
 # ... write code, make commits ...
 
-# 4. Push everything and create PRs
-gh stack push
+# 4. Push everything and create Stacked PRs
+gh stack submit
 
 # 5. Reviewer requests changes on the first PR
 gh stack bottom
@@ -30,7 +30,7 @@ gh stack bottom
 # 6. Rebase the rest of the stack on top of your fix
 gh stack rebase
 
-# 7. Push the updated stack
+# 7. Push the updated branches
 gh stack push
 
 # 8. When the first PR is merged, sync the stack
@@ -65,8 +65,8 @@ gh stack add -Am "API routes"
 gh stack add -Am "Frontend components"
 #    → creates feat/03
 
-# 7. Push everything
-gh stack push
+# 7. Push everything and create PRs
+gh stack submit
 ```
 
 Each `gh stack add -Am "..."` stages all files, commits, and (if the current branch already has commits) creates a new branch — no separate `git add` or `git commit` needed.
@@ -175,5 +175,5 @@ With the skill installed, your agent can:
 - Plan stack structure based on the work being done
 - Create branches and commit changes in the right layers
 - Navigate between branches to make mid-stack changes
-- Push and create PRs with proper base branches
+- Push branches and create stacked PRs
 - Rebase after making changes to lower layers
diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx
@@ -67,7 +67,12 @@ gh stack add auth-layer
 # ... make commits ...
 gh stack add api-routes
 # ... make commits ...
+
+# Push all branches
 gh stack push
+
+# Open a stack of PRs
+gh stack submit
 ```
 
 Ready to dive in? Start with the [Quick Start guide](/gh-stack/getting-started/quick-start/) or read the [full overview](/gh-stack/introduction/overview/).
diff --git a/docs/src/content/docs/introduction/overview.md b/docs/src/content/docs/introduction/overview.md
@@ -76,7 +76,8 @@ While the PR UI provides the review and merge experience, the `gh stack` CLI han
 
 - **Creating branches** — `gh stack init` and `gh stack add` create and track branches in the correct dependency order.
 - **Keeping branches rebased** — `gh stack rebase` cascades changes through the stack, handling both regular and squash-merged PRs.
-- **Pushing and creating PRs** — `gh stack push` pushes all branches and creates or updates PRs with the correct base branches.
+- **Pushing branches** — `gh stack push` pushes all branches to the remote.
+- **Creating PRs** — `gh stack submit` pushes branches and creates or updates PRs, linking them as a Stack on GitHub.
 - **Navigating the stack** — `gh stack up`, `down`, `top`, and `bottom` let you move between layers without remembering branch names.
 - **Syncing everything** — `gh stack sync` fetches, rebases, pushes, and updates PR state in one command.
 
diff --git a/docs/src/content/docs/reference/cli.md b/docs/src/content/docs/reference/cli.md
@@ -111,30 +111,51 @@ gh stack add -um "Update docs" docs-layer
 
 ## `gh stack push`
 
-Push all branches in the current stack and create or update pull requests.
+Push all branches in the current stack to the remote.
 
 ```sh
 gh stack push [flags]
 ```
 
-Pushes every branch to the remote, then for each branch either creates a new PR (with the correct base branch) or updates the base of an existing PR if it has changed. Uses `--force-with-lease` by default to safely update rebased branches.
+Pushes every branch to the remote using `--force-with-lease --atomic`. This is a lightweight wrapper around `git push` that knows about all branches in the stack. It does not create or update pull requests — use `gh stack submit` for that.
+
+| Flag | Description |
+|------|-------------|
+| `--remote <name>` | Remote to push to (defaults to auto-detected remote) |
+
+**Examples:**
+
+```sh
+gh stack push
+gh stack push --remote upstream
+```
+
+---
+
+## `gh stack submit`
+
+Push all branches and create/update PRs and the stack on GitHub.
+
+```sh
+gh stack submit [flags]
+```
+
+Creates a Stacked PR for every branch in the stack, pushing branches to the remote. After creating PRs, `submit` automatically creates a **Stack** on GitHub to link the PRs together. If the stack already exists on GitHub (e.g., from a previous submit), new PRs are added to the existing stack.
 
 When creating new PRs, you will be prompted to enter a title for each one. Press Enter to accept the default (branch name), or use `--auto` to skip prompting entirely.
 
 | Flag | Description |
 |------|-------------|
 | `--auto` | Use auto-generated PR titles without prompting |
 | `--draft` | Create new PRs as drafts |
-| `--skip-prs` | Push branches without creating or updating PRs |
 | `--remote <name>` | Remote to push to (defaults to auto-detected remote) |
 
 **Examples:**
 
 ```sh
-gh stack push
-gh stack push --auto
-gh stack push --draft
-gh stack push --skip-prs
+gh stack submit
+gh stack submit --auto
+gh stack submit --draft
 ```
 
 ---
@@ -264,39 +285,6 @@ gh stack checkout
 
 ---
 
-## `gh stack unstack`
-
-Remove a stack from local tracking and optionally delete it on GitHub.
-
-```sh
-gh stack unstack [branch] [flags]
-```
-
-If no branch is specified, uses the current branch to find the stack. By default, the stack is removed from both local tracking and GitHub. Use `--local` to only remove the local tracking entry.
-
-| Flag | Description |
-|------|-------------|
-| `--local` | Only delete the stack locally (keep it on GitHub) |
-
-| Argument | Description |
-|----------|-------------|
-| `[branch]` | A branch in the stack to delete (defaults to the current branch) |
-
-**Examples:**
-
-```sh
-# Remove the stack from local tracking and GitHub
-gh stack unstack
-
-# Only remove local tracking
-gh stack unstack --local
-
-# Specify a branch to identify the stack
-gh stack unstack feature-auth
-```
-
----
-
 ## Navigation
 
 Move between branches in the current stack without having to remember branch names.
@@ -388,3 +376,4 @@ gh stack alias gst --remove
 | 5 | Invalid arguments or flags |
 | 6 | Disambiguation required (branch belongs to multiple stacks) |
 | 7 | Rebase already in progress |
+| 8 | Stack is locked by another process |
