CLI Command Reference

create-repo

Create a new repository with a backdated initial commit.
Purpose: Initializes a local Git repository in a new directory, makes the first commit (with an optional past date), and creates a remote GitHub repository (via gh repo create), pushing the initial commit to it.

Usage:

legends create-repo <name> [--owner <org-or-username>] [--description "<text>"] \
  [--branch <main|trunk|...>] [--message "Initial commit message"] \
  [--date "<YYYY-MM-DD HH:MM:SS>"] [--author-name "<name>"] [--author-email "<email>"] \
  [--private | --public] [--remote <origin-name>]

• <name>: The repository name (also the name of the local directory that will be created). This is required.
• --owner: (Optional) The GitHub username or organization under which to create the repo. If not provided, defaults to the configured owner or the authenticated user.
• --description: (Optional) A description for the repository (will be added to the README and set on GitHub).
• --branch: (Optional) The default branch name to use (e.g., main, master, trunk). If not specified, uses the default from config (which is usually "main").
• --message: (Optional) Initial commit message. Defaults to "Initial commit" if not given.
• --date: (Optional) The timestamp for the initial commit. You can use formats like "2024-12-01 12:00:00" or ISO8601 "2024-12-01T12:00:00". If not provided, the initial commit will use the current date/time (or you can configure a default).
• --author-name / --author-email: (Optional) Override the author’s name/email for the initial commit. If not provided, GitLegends will use your GitHub identity (retrieved via the GitHub CLI) or fall back to your global git config.
• --private / --public: By default, repositories are created private (unless configured otherwise). Use --public to create a public repository. These are mutually exclusive flags.
• --remote: (Optional) The name of the git remote to create (default is "origin"). Usually you won’t need to change this.

What it does:

• Creates the local directory and initializes a git repo.
• Creates a README file (with title and description).
• Commits the README (with the specified or default message and date).
• Sets the default branch name (if not main).
• Uses gh repo create to create the repo on GitHub (with --private or --public flag and the description).
• Adds the GitHub repo as a remote and pushes the initial commit (setting upstream to the given remote name).

Important: If the directory already exists and is non-empty, the command will abort to avoid messing with existing content. Choose a new directory or ensure the target is empty.

create-branch

Create a new branch from an existing base branch, and record its creation with a backdated empty commit (a “branch birth” commit).

Usage:

legends create-branch <branch-name> [--base <base-branch>] \
  --date "<YYYY-MM-DD HH:MM:SS>" [--message "<commit message>"] [--push]

• <branch-name>: The name of the new branch to create.
• --base: (Optional) Name of the base branch from which to create the new branch. Default is the configured base (usually "main"). The base branch must exist (locally or on origin).
• --date: (Required) The timestamp for the branch creation commit. This must be provided, as the point of this command is to create a backdated commit.
• --message: (Optional) Commit message for the empty commit. If not provided, a default message like chore(<branch>): branch birth with the date will be used.
• --push: (Optional) If provided, pushes the new branch to the origin remote immediately.

What it does:

• Checks out the base branch and updates it (attempts to fetch if needed).
• Creates the new branch locally.
• Commits nothing (an empty tree state) with --allow-empty to produce an empty commit, using the provided date as the timestamp.
• If --push is specified, it will push the branch to origin. If it’s the first push of that branch, -u (set upstream) is used.

This command is useful to establish a historical start point for a feature branch before any changes are made on it.

commit

Create a backdated commit on a specified branch, optionally including changes.

Usage:

legends commit --branch <branch-name> --date "<YYYY-MM-DD HH:MM:SS>" \
  --message "<commit message>" [--allow-empty] [--add-all] [--touch <file>] [--push]

• --branch: (Required) The target branch for the commit. The branch should exist; if it doesn’t, GitLegends will attempt to create it (from the base branch).
• --date: (Required) Timestamp for the commit.
• --message: (Required) Commit message.
• --allow-empty: (Optional) Allow an empty commit if no changes are staged. Without this, the commit command would abort if no changes are present.
• --add-all: (Optional) Stage all modified/new files (git add -A) before committing. Use this to easily include all current changes in the commit.
• --touch <file>: (Optional) Specify a file path to "touch" (create or update the timestamp of) before committing. This is a quick way to ensure there’s content to commit (especially combined with --allow-empty, it can create a file so that the commit isn’t actually empty).
• --push: (Optional) Push the branch to the remote after committing. If it’s the first push of that branch, -u (set upstream) is used.

What it does:

• Checks out the given branch (if the branch doesn’t exist locally, it will attempt to create it from the base branch).
• If --touch is used, it will create the file (or update its modified time) and stage it.
• If --add-all is used, all changes in the repository will be staged.
• Creates a commit with the given message. The environment is configured so that the commit’s author and committer dates are set to the provided --date. The author name/email and committer name/email are derived from your configuration or GitHub identity.
• If --allow-empty is not set and there are no changes to commit, the command will error out (to avoid accidental empty commits). If --allow-empty is set, it will go ahead and create a commit even if nothing changed (Git allows explicitly empty commits when --allow-empty is used).
• If --push is specified, it pushes the commit to the remote. If the branch has not been pushed before, GitLegends will set the upstream (equivalent to git push -u origin <branch>).

Use the commit command for adding one historical commit at a time to a branch. You can repeat it to simulate a series of changes on a feature branch, each at different points in time.

open-pr

Open a pull request on GitHub for a branch against a base branch.

Usage:

legends open-pr --branch <source-branch> [--base <target-branch>] \
  [--title "<PR title>"] [--body "<PR description>"] [--draft]

• --branch: (Required) The source branch (head branch) of the PR. This is the feature branch you want to merge from.
• --base: (Optional) The target branch into which the PR will merge. Default is the configured base (often "main").
• --title: (Optional) Title for the PR. If not provided, GitLegends might use the branch name or a default format (for example, it could use a template that prefixes “Feature:” or similar to the branch name).
• --body: (Optional) Body text for the PR description. Can include Markdown.
• --draft: (Optional) If set, the PR will be opened as a draft on GitHub (indicating it’s not ready for final review).

What it does:

• Ensures the source branch is pushed to the remote. If not, it pushes it (setting upstream if needed). This prevents errors like “no commits between base and head” when creating the PR.
• Runs the GitHub CLI command to create the PR. This will create the PR on GitHub under your repository, with the given title/body.
• If successful, you’ll have an open PR on GitHub. GitLegends, at this stage, doesn’t automatically approve or merge it (that’s handled in other steps or by using commit-all or manual steps). It simply opens the PR and leaves it open.

Note: The PR’s creation time on GitHub will be the current time. This cannot be changed. However, the commits inside the PR will carry whatever dates you gave them when committing.

You can use open-pr after you’ve prepared your branch with commits (and usually after pushing them). If you attempt to open a PR for a branch with no new commits relative to base, GitHub might not create an empty PR, so ensure you have at least one commit ahead of the base.

merge-pr

Merge a pull request (or branch) with a backdated merge commit, and optionally close the PR and clean up the branch.

Usage:

legends merge-pr [--branch <source-branch> | --pr <PR-number>] \
  [--base <target-branch>] --date "<YYYY-MM-DD HH:MM:SS>" \
  [--message "<merge commit message>"] [--delete-branch | --no-delete-branch]

• --branch: The source branch (feature branch) to merge. You can specify this or a PR number.
• --pr: The pull request number to merge. If you provide --pr, GitLegends will find the corresponding head branch automatically (so you can omit --branch in that case).
• --base: (Optional) The base branch to merge into. Defaults to the configured base (e.g., main).
• --date: (Required) The timestamp for the merge commit.
• --message: (Optional) A custom commit message for the merge commit. If not provided, a default will be used:
  • If a PR number is known, something like "Merge pull request #<PR> from <branch>".
  • If no PR (just merging a branch), "Merge branch '<branch>' into <base>".
• --delete-branch / --no-delete-branch: By default, GitLegends will delete the remote branch after merging (and if a PR was open, close the PR). You can explicitly use --no-delete-branch to keep the branch around. Conversely, --delete-branch ensures the branch is removed. These are toggle flags; by default deletion is on.

What it does:

• Checks out the base branch locally and updates it from the remote.
• Determines the source branch to merge (either from --branch or by looking up the --pr for its branch name).
• Performs a merge without committing: essentially git merge --no-ff --no-commit <source-branch>. This brings the changes into the index but waits for a commit.
• Creates a merge commit with the specified --date as the timestamp. This commit will have two parents (like a normal merge) and include the changes from the feature branch. The commit author/committer can be set to mimic how GitHub does it (often the committer is the GitHub user performing the merge).
• Pushes the base branch to the remote, so the merge commit appears on GitHub.
• If --delete-branch is in effect, the tool will then:
  • If a PR number was provided or found, attempt to close the PR on GitHub using gh pr close --delete-branch. This will mark it as merged (if not already by pushing) and delete the branch in one go.
  • If no PR number (just merging a branch), or if the GH CLI call fails, it will fall back to deleting the remote branch via git push origin --delete <branch>.
• If --no-delete-branch was specified, it will leave the branch and PR as-is (useful if you want to keep the PR open or branch undeleted for some reason).

Use case: This command is used after you have an open PR and you’re ready to merge it with a historical date. It’s typically the final step in the workflow, and by default it cleans up the PR/branch to mirror how one would usually delete the feature branch after merge on GitHub.

commit-all

Run an entire commit → PR → merge workflow in one command (optionally with an approval review and comment).

Usage:

legends commit-all --branch <feature-branch> [--base <base-branch>] \
  --commit-date "<YYYY-MM-DD HH:MM:SS>" --message "<commit message>" \
  [--touch <file>] [--allow-empty] \
  [--pr-title "<PR Title>"] [--pr-body "<PR Body>"] [--draft] \
  --merge-date "<YYYY-MM-DD HH:MM:SS>" [--delete-branch] \
  [--review] [--review-body "<text>"] [--comment "<text>"]

• --branch: (Required) The feature branch name to use or create.
• --base: (Optional) Base branch to start from (default is "main" or configured base).
• --commit-date: (Required) The date for the feature commit.
• --message: (Required) Commit message for the feature commit.
• --touch: (Optional) A file to create/modify before the commit (to ensure there’s content to commit).
• --allow-empty: (Optional) Allow the commit to be empty if no changes (just like in the commit command).
• --pr-title: (Optional) Title for the pull request. Defaults to the commit message if not provided.
• --pr-body: (Optional) Body text for the PR.
• --draft: (Optional) Open the PR as a draft.
• --merge-date: (Required) The date for the merge commit.
• --delete-branch: (Optional flag) Delete the branch after merging (default behavior is true, so you can use --no-delete-branch in CLI as well; here specifying --delete-branch just makes it explicit).
• --review: (Optional flag) If set, GitLegends will immediately add an approval review to the PR (as the authenticated user) after creating it.
• --review-body: (Optional) If --review is set, you can customize the review comment (default would be something like "LGTM").
• --comment: (Optional) A separate top-level comment to post on the PR after creation (e.g., to provide additional info or just simulate a conversation).

What it does:

• Checks if the feature branch exists locally. If not, it will create it from the base.
• If --touch is provided, creates that file. Otherwise, it stages all changes (equivalent to git add -A) unless you use --allow-empty with no changes.
• Commits the changes with the given message and --commit-date.
• Pushes the feature branch to origin.
• Opens a PR on GitHub with the given title/body (or defaults).
• If --review was specified, it uses the GitHub CLI to add an approving review to the PR (as if you reviewed your own PR).
• If --comment was specified, it posts a comment on the PR.
• Checks out the base branch, pulls latest changes, then merges the feature branch using the --merge-date for the commit timestamp.
• Pushes the base branch (with the new merge commit).
• If --delete-branch (default behavior) is active, it closes the PR on GitHub and deletes the remote branch (just like the merge-pr command’s cleanup).

The result is the PR appears as merged on GitHub, the commits are in the history with the specified dates, and the feature branch is removed.

This one-shot command is extremely useful when you want to script a series of events quickly. For example, you could call commit-all multiple times to simulate multiple features being developed and merged in sequence. It essentially combines commit, open-pr, merge-pr, and some GitHub interactions (review/comment) into one convenient package.