CLI Reference

The gf command-line tool lets you manage repositories, authentication, and tokens from your terminal.

Installation

npm (global)

npm install -g @gitforge/cli

Homebrew

brew install gitforge/tap/gf

Binary (Linux/macOS)

curl -fsSL https://gitforge.dev/install.sh | sh

Verify installation:

gf --version

Commands

gf auth login

Authenticate with your GitForge account. Opens a browser for OAuth flow or accepts a PAT via stdin.

Flags

--token <pat>Authenticate with a Personal Access Token instead of browser flow

--host <url>GitForge instance URL (default: https://gitforge.dev)

Examples

Interactive login

gf auth login

gf auth login --token gf_YOUR_PAT

gf auth login --host https://git.mycompany.com

gf auth status

Show the currently authenticated user and instance.

Examples

Check auth status

gf auth status

gf auth logout

Remove stored credentials for the current or specified host.

Flags

--host <url>Logout from a specific instance

Examples

Logout

gf auth logout

gf repo list

List repositories you have access to.

Flags

--limit <n>Maximum number of repos to show (default: 30)

--visibility <v>Filter by visibility: public, private, or all (default: all)

--jsonOutput as JSON

Examples

List all repos

gf repo list

List as JSON

gf repo list --json

Only public repos

gf repo list --visibility public

gf repo create

Create a new repository.

Flags

--name <name>Repository name (required)

--description <desc>Repository description

--visibility <v>public or private (default: private)

--cloneClone the repo locally after creation

Examples

Create a private repo

gf repo create --name my-project

Create and clone

gf repo create --name my-project --clone

Create public repo

gf repo create --name oss-lib --visibility public --description "Open source library"

gf repo clone

Clone a repository. Automatically configures authentication.

Flags

--depth <n>Create a shallow clone with n commits

Examples

Clone a repo

gf repo clone my-org/my-project

Shallow clone

gf repo clone my-org/my-project --depth 1

gf repo delete

Delete a repository. Requires confirmation.

Flags

--yesSkip confirmation prompt

Examples

Delete a repo

gf repo delete my-org/my-project

Delete without prompt

gf repo delete my-org/my-project --yes

gf token create

Create a new Personal Access Token.

Flags

--name <name>Token name (required)

--expiry <days>Token expiry in days (default: 90)

--scopes <scopes>Comma-separated list of scopes (default: repo)

Examples

Create a token

gf token create --name ci-deploy

Token with expiry

gf token create --name ci-deploy --expiry 30

Token with scopes

gf token create --name read-only --scopes repo:read

gf token list

List your Personal Access Tokens.

Flags

--jsonOutput as JSON

Examples

List tokens

gf token list

gf token revoke

Revoke a Personal Access Token by name or ID.

Examples

Revoke a token

gf token revoke ci-deploy

gf status

Show connection status, authenticated user, and current repository info.

Examples

Check status

gf status

gf init

Initialize a new Git repository with GitForge remote preconfigured.

Flags

--name <name>Repository name on GitForge

--visibility <v>public or private (default: private)

Examples

Init and link

gf init --name my-project

Global Flags

--host <url>GitForge instance URL (default: https://gitforge.dev)

--jsonOutput in JSON format (where supported)

--verboseEnable verbose logging

--versionPrint CLI version

--helpShow help for any command

Environment Variables

GF_TOKENPersonal Access Token (overrides stored credentials)

GF_HOSTGitForge instance URL

GF_NO_COLORDisable colored output