velo CLI Reference

The velo CLI lets you interact with VeloGit from your terminal — manage pull requests, inspect pipeline runs, work with Ghost Workspace fragments, and run your ritual pipeline locally.

Installation

Download the latest release from velogit.com/velogit/velogit and place the velo binary somewhere on your PATH.

Authentication

Before using any command that talks to the API, authenticate with a Personal Access Token. Generate one in Settings → Developer Settings on velogit.com.

`velo auth login`

Save your API URL and token to the local config.

velo auth login --url https://api.velogit.com --token velo_abc123

Flag	Description
`--url`	Base URL of the VeloGit API
`--token`	Personal Access Token (`velo_...`)

`velo auth status`

Show the currently configured API URL and token (masked).

velo auth status

Pull Requests

`velo pr list`

List pull requests for a repository.

velo pr list --org myorg --repo myrepo
velo pr list --org myorg --repo myrepo --status open

Flag	Description
`--org`	Organization name
`--repo`	Repository name
`--status`	Filter: `open`, `merged`, `closed`

`velo pr view <id>`

View a pull request’s details including status and reviewers.

velo pr view abc123 --org myorg --repo myrepo

`velo pr create`

Open a new pull request.

velo pr create --org myorg --repo myrepo \
  --title "Fix login bug" \
  --source fix/login \
  --target main

Flag	Description
`--title`	PR title
`--source`	Source branch
`--target`	Target branch (default: `main`)
`--body`	PR description
`--draft`	Create as draft

`velo pr merge <id>`

Merge an open pull request.

velo pr merge abc123 --org myorg --repo myrepo

`velo pr close <id>`

Close a pull request without merging.

velo pr close abc123 --org myorg --repo myrepo

Pipeline Runs

`velo pipeline list`

List pipeline runs for a repository.

velo pipeline list --org myorg --repo myrepo
velo pipeline list --org myorg --repo myrepo --status running

Flag	Description
`--status`	Filter: `running`, `waiting_gate`, `passed`, `failed`, `rejected`, `canceled`

`velo pipeline view <run-id>`

View a run and its step statuses.

velo pipeline view abc123 --org myorg --repo myrepo

`velo pipeline logs <run-id>`

Print step logs for a run.

velo pipeline logs abc123 --org myorg --repo myrepo
velo pipeline logs abc123 --org myorg --repo myrepo --step test

Flag	Description
`--step`	Show logs for a single named step only

`velo pipeline approve <run-id>`

Approve a gate step so the pipeline continues.

velo pipeline approve abc123 --org myorg --repo myrepo --step approve-deploy

Flag	Description
`--step`	Gate step name to approve (required)

`velo pipeline reject <run-id>`

Reject a gate step and stop the pipeline.

velo pipeline reject abc123 --org myorg --repo myrepo --step approve-deploy

Ghost Workspace Fragments

`velo fragment list`

List Shadow Fragments in the Ghost Workspace.

velo fragment list --org myorg --repo myrepo
velo fragment list --org myorg --repo myrepo --status pending

Flag	Description
`--status`	Filter: `pending`, `melded`, `dismissed`

`velo fragment view <id>`

View a fragment’s proposed diff. If the fragment was generated with a prompt (via velo fragment create or the Ghost Workspace “Request suggestion” button), the golden prompt and model are shown above the diff so reviewers can see the intent behind the change.

velo fragment view abc123 --org myorg --repo myrepo

`velo fragment create`

Request a new fragment by prompting the agent. The prompt is stored as the “golden prompt” on the resulting fragment so reviewers can see the intent behind the diff.

velo fragment create --org myorg --repo myrepo \
  --prompt "Refactor auth middleware to extract token validation"

# Give the agent specific files as context
velo fragment create --org myorg --repo myrepo \
  --prompt "Add input validation" \
  --file internal/server.go \
  --file internal/auth.go

# Block until the agent finishes
velo fragment create --prompt "Add a unit test for this function" --wait

Flag	Description
`--prompt`	Instruction for the agent (required)
`--file`	File path to include as context (repeatable)
`--branch`	Branch to read file content from (default: `main`)
`--wait`	Block until the agent finishes generating the fragment

The command returns immediately with a fragment ID and generating status. The Ghost Workspace UI polls for completion, or use --wait to block in the terminal. Use velo fragment view <id> to check progress.

`velo fragment meld <id>`

Accept a fragment and apply it to the repository.

velo fragment meld abc123 --org myorg --repo myrepo

`velo fragment dismiss <id>`

Reject and dismiss a fragment without applying it.

velo fragment dismiss abc123 --org myorg --repo myrepo

Running Pipelines Locally

velo run executes your .velo/rituals.yaml pipeline on your local machine using Docker or Podman — no push required. Useful for testing pipelines before committing, or debugging a failing step.

Prerequisites

Docker or Podman must be installed and available on your PATH. Run docker info or podman info to verify.

`velo run`

Run all steps defined in .velo/rituals.yaml from the current directory.

velo run

The command:

Reads .velo/rituals.yaml
Pulls environment.base_image
Starts a container with the repo bind-mounted to /workspace
Executes each step in sequence, streaming output live
Stops the container when complete or on Ctrl+C

Gate steps pause and prompt for confirmation. Press Enter to continue, Ctrl+C to abort.

─── approve-deploy
[approve-deploy] Gate reached. Press Enter to continue or Ctrl+C to abort...

Critical steps (critical: true in the yaml) abort the entire run on failure. Non-critical step failures are logged and the run continues.

Options

Flag	Description
`--list`	Print the steps in `.velo/rituals.yaml` and exit (no container, nothing executed)
`--step <name>`	Run only this named step
`--from <name>`	Start from this step (inclusive), skip earlier ones
`--skip-gates`	Auto-approve all gate steps without prompting
`--env-file <path>`	Load environment variables from a file
`--runtime <docker\|podman>`	Force a specific container runtime (default: auto-detect)

Listing steps

velo run --list prints the step plan without executing anything. Useful for checking the order, finding a step name for --step / --from, or piping the step list to other tools with --json.

velo run --list

# →
# #   NAME                     TYPE     ON     CRITICAL
# 1   clone-oss                command  push   yes
# 2   overlay-saas-files       command  push   yes
# 3   build                    command  push   yes
# 4   test                     command  push
# 5   approve-deploy           gate     push
# 6   deploy-setup             command  push   yes
# ...

velo run --list --json

Secrets and environment variables

Secrets are passed as environment variables into the container. velo run loads them in this order:

If .env.local exists in the current directory, it is loaded automatically
--env-file <path> loads a specific file (overrides the auto-detect)

.env.local format — standard KEY=VALUE, quotes are stripped, # comments are ignored:

OSS_CLONE_URL="https://git:mytoken@velogit.com/myorg/myrepo.git"
DATABASE_URL=postgres://user:pass@localhost/mydb

Examples

# Run the full pipeline
velo run

# Test only the build step
velo run --step build

# Resume from the test step (e.g. after fixing a build failure)
velo run --from test

# Run a deploy pipeline locally, skipping the approval gate
velo run --from deploy-setup --skip-gates

# Use Podman instead of Docker
velo run --runtime podman

# Load secrets from a custom file
velo run --env-file .env.staging

Global flags

Flag	Description
`--json`	Output command results as JSON (supported on most commands)
`--help`	Show help for any command