gv — GitVerse CLI

A full-featured command-line interface for GitVerse, covering all Public API v1 endpoints. Inspired by gh (GitHub CLI).

📦 Releases

Installation

Download pre-built binaries from the latest release.

From source (requires Go 1.23+):

go install gitverse.ru/ifl/gv-go/cmd/gv@latest

Build locally:

git clone https://gitverse.ru/ifl/gv-go.git
cd gv-go
make build
# binary: ./gv

Cross-compile for all platforms:

make cross
# outputs in dist/

Authentication

gv uses a personal access token stored in ~/.config/gv/config.yml.

Login interactively:

gv auth login
# Enter your GitVerse token: <paste token>
# Logged in as ifl

Login non-interactively (CI/scripts):

echo "$GITVERSE_TOKEN" | gv auth login --with-token

Or use the environment variable directly (no login needed):

export GITVERSE_TOKEN=your_token
gv repo list

Check status:

gv auth status
# Logged in to api.gitverse.ru as ifl

Logout:

gv auth logout

Command Reference

All commands accept --json to output raw JSON, and --token / --host to override config.

Repo auto-detection

Commands that take [owner/repo] will auto-detect the repository from git remote get-url origin when run inside a cloned repo. You can always pass owner/repo explicitly to override.

# Inside a cloned repo — owner/repo is inferred automatically:
gv repo view
gv issue list
gv pr list

# Or explicit:
gv repo view ifl/my-repo
gv issue list ifl/my-repo

Repositories

gv repo list                          # List your repositories
gv repo view                         # View current repo details (auto-detected)
gv repo view ifl/my-repo             # View repo details (explicit)
gv repo create my-repo               # Create a new repo
gv repo create my-repo --private --auto-init -d "My project"
gv repo edit -d "New description"
gv repo delete --confirm
gv repo commits
gv repo commits --sha feature/branch
gv repo file README.md
gv repo languages
gv repo forks
gv repo fork
gv repo compare main feature/branch
gv repo collaborator list
gv repo collaborator add alice --permission write
gv repo collaborator remove alice --confirm
gv repo secret list
gv repo secret set MY_SECRET value123
gv repo secret delete MY_SECRET --confirm
gv repo variable list
gv repo variable set MY_VAR value123
gv repo variable delete MY_VAR --confirm

Issues

gv issue list                        # List open issues (auto-detected repo)
gv issue list --state closed
gv issue view 42                     # View issue #42
gv issue create "Bug: crash on startup" -b "Steps to reproduce..."
gv issue edit 42 --title "New title"
gv issue close 42
gv issue comment 42 "Thanks for the report!"
gv issue label list 42
gv issue label add 42 bug enhancement
gv issue label remove 42 bug
gv issue timeline 42

Pull Requests

gv pr list                           # List open PRs (auto-detected repo)
gv pr view 7                         # View PR #7
gv pr create feature/login "Add login flow" --base main
gv pr edit 7 --title "Updated title"
gv pr merge 7 --confirm              # Merge PR (default: merge commit)
gv pr merge 7 --method squash --confirm
gv pr close 7
gv pr checkout 7                     # Fetch and checkout PR branch locally
gv pr commits 7
gv pr files 7
gv pr update-branch 7

Organizations

gv org members my-org                # List members
gv org teams my-org                  # List teams
gv org repos my-org                  # List repositories

gv org team list my-org              # Same as org teams
gv org team view my-org devs         # List team members
gv org team add-repo my-org devs ifl/my-repo --permission write
gv org team add-member my-org devs alice

gv org member check my-org alice
gv org member remove my-org alice --confirm

gv org secret list my-org
gv org secret set my-org MY_SECRET value123
gv org secret delete my-org MY_SECRET --confirm
gv org variable list my-org
gv org variable set my-org MY_VAR value123
gv org variable delete my-org MY_VAR --confirm

Runners

gv runner list                       # List repo runners (auto-detected)
gv runner list --org my-org          # List org runners
gv runner view 1                     # View runner details
gv runner delete 1
gv runner delete 1 --org my-org
gv runner reg-token
gv runner reg-token --org my-org

Releases

gv release list
gv release view 1
gv release create v1.0.0 --name "My Release" --body "Changes"
gv release delete 1 --confirm

Branches

gv branch list

Workflow

gv workflow dispatch release.yaml --ref main --input version=1.0.0

Users

gv user view alice
gv user search "alice"

Stars

gv star list
gv star add ifl/my-repo
gv star remove ifl/my-repo

Artifacts

gv artifact list                     # List artifacts (auto-detected repo)
gv artifact view 42
gv artifact delete 42 --confirm
gv artifact download 29 binaries     # Download artifact zip (run-id, artifact-name)
gv artifact download 29 binaries -o release.zip

Git Objects

gv git refs
gv git tree <sha> --recursive
gv git commit <sha>

Pages

gv pages list
gv pages deploy --artifact-url <url>

Smartclass

gv smartclass assignment view 42

Global Flags

Flag	Description
`--token string`	Override stored auth token (caution: value visible in process list)
`--host string`	GitVerse API host (default: `api.gitverse.ru`)
`--json`	Output raw JSON instead of formatted table

Using `--json`

All commands support --json for scripting:

# Get clone URL of a repo (auto-detected)
gv repo view --json | jq -r '.clone_url'

# List only open PR numbers
gv pr list --json | jq '.[].number'

# Find runners that are busy
gv runner list --json | jq '.runners[] | select(.busy == true)'

Releasing

Releases are built and published automatically by CI when a version tag is pushed.

Create and push a tag:

git tag v1.2.3
git push origin v1.2.3

Or trigger manually via CI/CD -> Workflows -> Release -> Run workflow, entering the version (e.g. v1.2.3).

The workflow cross-compiles for all platforms and publishes a GitVerse release with binaries attached. Requires the GV_TOKEN secret set in repo CI/CD settings.

Contributing

Fork the repo on GitVerse: gv repo create gv-go --auto-init
Clone it and create a branch
Make changes, add tests
Run go test ./... and go vet ./...
Open a PR: gv pr create your-branch "Your feature"

Bug reports and PRs welcome at https://gitverse.ru/ifl/gv-go.