gh-project

List projects owned by the currently authenticated user

$ gh project [[ls|list]]

$ gh project [[ls|list]] --owner [owner]

$ gh project view [number] --owner [owner]

$ gh project create --owner [owner] --title [project_title]

$ gh project item-add [number] --owner [owner] --url [issue_or_pr_url]

$ gh project item-list [number] --owner [owner]

$ gh project close [number] --owner [owner]

gh project <command> [<arguments>] [<flags>]
gh project item <subcommand> [<arguments>] [<flags>]
gh project field <subcommand> [<arguments>] [<flags>]

Examples:
gh project list --owner monalisa
gh project view 1 --owner github
gh project create --title "New Initiative" --org octocats
gh project item add 123 --url https://github.com/cli/cli/issues/4567

--help, -h
    Display help for the command or subcommand.

--owner <login>
    Specify the login of the user or organization that owns the project. Required for some commands if not run from a repository context, or to specify projects not owned by the current user/repo.

--org <login>
    An alias for --owner <login> when the project owner is an organization.

--limit <number>
    Limit the number of results returned, useful for commands like list.

--format <string>
    Print output in a specific format using a Go template string.

--jq <expression>
    Filter JSON output using a jq expression.

--web
    Open the project in the default web browser. Applicable with commands like view.

--title <string>
    Specify the title for a new project or when editing an existing one.

--body <string>
    Provide a description or body content for a new project or when editing.

--url <string>
    Specify the URL of an item (e.g., issue, pull request, draft issue) to add to a project.

gh project is a powerful subcommand of the GitHub CLI (gh) designed for comprehensive management of GitHub Projects directly from the terminal. It provides a full suite of functionalities for project lifecycle management, including creating, listing, viewing, editing, closing, reopening, and deleting projects. Beyond core project management, gh project enables detailed manipulation of project items—such as issues, pull requests, and draft items—through subcommands like item add, item list, item edit, item archive, and item delete. Furthermore, it supports managing custom fields within projects, allowing users to field list, field create, field view, field edit, and field delete project fields. This command streamlines project workflows by integrating seamlessly into the developer's terminal environment, significantly enhancing productivity for individuals and teams leveraging GitHub's project boards.

Using gh project requires the GitHub CLI to be installed and properly authenticated with GitHub (via gh auth login). Project operations are tightly coupled with GitHub's Project API v2, which may have specific data structures and limitations. Users must possess appropriate permissions on the repository, organization, or user account to manage projects. All operations require an active internet connection to GitHub.

All gh project operations rely on an authenticated session with GitHub. Users must first authenticate using the gh auth login command, which stores credentials for subsequent CLI operations.

gh project primarily interacts with GitHub's newer Projects V2. While it can list classic projects, most item and field manipulation features are designed for the advanced capabilities of the Projects V2 system. Be aware of which project version you are targeting.

Many gh project commands, especially those for creating or modifying projects, require explicit specification of the project's owner (a user or an organization) using the --owner or --org flags. This is crucial when operating outside of a specific repository context or when managing projects not owned by the authenticated user.

The gh project command was introduced as a core component of the GitHub CLI to provide a native command-line interface for managing GitHub's evolving Project features. Its development directly addresses the newer, more powerful Projects V2 (often referred to as 'Projects (beta)' during its development phase), which offer flexible table-based project boards. The command's inclusion aligns with GitHub's broader strategy to enable more development and project management workflows directly from the terminal, making project management seamless for developers already utilizing the CLI for code, issues, and pull requests.

gh(1), gh auth(1), gh issue(1), gh pr(1), gh repo(1), git(1)