CHAMPREP Code commands
champrep code works with CHAMPREP Code from your terminal: projects and
branches, bulk cloning, merge requests, issues, pipelines and job logs, CI
runners, and releases. It
acts as you, with your normal CLI sign-in, so Code applies your role in each
project, your plan, and your quotas exactly as the web app does.
Before you start
Section titled “Before you start”- Install the CLI and sign in with
champrep auth login. - Your plan must include CHAMPREP Code. When it does not, commands stop with
not available to your account(exit code1).
champrep auth loginchamprep code projects lsNaming projects, merge requests and issues
Section titled “Naming projects, merge requests and issues”PROJECTis the project’s full path, such asacme/web, or its ID. The path is the easiest to type.- Merge requests and issues are numbered per project. Pass the number:
12and!12both name merge request 12, and34and#34both name issue 34. PIPELINE_IDandJOB_IDare the numbers shown bypipelines lsandjobs ls.
Commands
Section titled “Commands”Projects and repositories
Section titled “Projects and repositories”| Command | Purpose |
|---|---|
champrep code projects ls | List the projects you are a member of. --search TEXT, --all (also public and internal projects you can see), --limit N. |
champrep code projects show PROJECT | Show a project, its default branch, and its clone addresses. |
champrep code projects create NAME | Create a project in your personal namespace, or in a group with --namespace. Also --path, --visibility private|internal|public, --description, --default-branch. |
champrep code repo clone-url PROJECT | Print the HTTPS clone address (--ssh for the SSH address). |
champrep code clone PROJECT... | Clone projects into --dest (default .), each under its namespace: DEST/<group>/<subgroup>/<project>. |
champrep code clone --group GROUP | Clone every project of a group; --include-subgroups adds every subgroup. |
champrep code clone --membership / --owned / --all | Clone every project you are a member of, where your role is Owner, or that you can see. |
champrep code branches ls PROJECT | List branches with their last commit. --search, --limit. |
champrep code ssh-keys ls | List the SSH keys on your Code account. |
code clone options:
--ssh, or--https(the default), picks the protocol.--dry-runlists what would happen.--parallel Nruns N git operations at once (default 4, at most 16).--archivedincludes archived projects.--updatefetches and fast-forwards projects already cloned instead of skipping them. A clone whoseoriginis another repository is reported asmismatch. A detached HEAD or a branch without an upstream is reported asno-upstream.--search TEXTkeeps only the projects that match.--max-projects Nhandles at most N projects (default 1000), counted after the--ownedfilter.
It prints a summary and exits 1 when any project failed or the run was
interrupted (Ctrl-C stops new clones and the running ones). With --json it
prints one entry per project with its status.
A bulk clone never prompts. git runs with GIT_TERMINAL_PROMPT=0, and SSH
runs with BatchMode=yes unless you set GIT_SSH_COMMAND or
core.sshCommand yourself. Only https:// and SSH addresses on the CHAMPREP
Code host are cloned, and git runs with every other transport disabled.
git authenticates on its own. Use an SSH key, or a personal access token kept
by git’s credential store, both set up once in the Code web app; see
set up git credentials. The CLI
never puts a token in a remote URL or in .git/config.
Merge requests
Section titled “Merge requests”mr also accepts merge-requests.
| Command | Purpose |
|---|---|
champrep code mr ls PROJECT | List merge requests. --state opened (default), merged, closed, locked or all; --mine; --search; --limit. |
champrep code mr show PROJECT IID | Show a merge request, its merge status, and its head pipeline. |
champrep code mr create PROJECT | Open a merge request. Requires --source, --target and --title; also --description, --draft, --remove-source-branch, --squash. |
champrep code mr merge PROJECT IID | Merge now, or with --auto when the pipeline succeeds. Also --squash, --remove-source-branch, --message, --sha. |
champrep code mr approve PROJECT IID | Approve. --sha pins the approval to the commit you reviewed. |
Issues
Section titled “Issues”| Command | Purpose |
|---|---|
champrep code issues ls PROJECT | List issues. --state opened (default), closed or all; --labels a,b; --search; --mine (assigned to you); --limit. |
champrep code issues show PROJECT IID | Show an issue. |
champrep code issues create PROJECT | Create an issue. Requires --title; also --description, --labels, --confidential, --due YYYY-MM-DD. |
champrep code issues close PROJECT IID | Close an issue. |
champrep code issues reopen PROJECT IID | Reopen a closed issue. |
Pipelines and jobs
Section titled “Pipelines and jobs”pipelines also accepts pl.
| Command | Purpose |
|---|---|
champrep code pipelines ls PROJECT | List pipelines, newest first. --ref, --status, --limit. |
champrep code pipelines show PROJECT PIPELINE_ID | Show a pipeline and every job in it. |
champrep code pipelines run PROJECT --ref REF | Run a pipeline on a branch or tag. --var KEY=VALUE adds a variable (repeatable). |
champrep code pipelines retry PROJECT PIPELINE_ID | Retry the failed and canceled jobs. |
champrep code pipelines cancel PROJECT PIPELINE_ID | Cancel a running pipeline. |
champrep code pipelines wait PROJECT [PIPELINE_ID] | Wait for a pipeline to finish: the given one, the newest of a commit with --sha SHA (or --sha HEAD in the repository; it waits for the pipeline to appear), or the newest on --ref BRANCH at that moment (default: the default branch). After a push, use --sha: --ref can still find the previous commit’s pipeline. Checks with a growing interval (5 s up to 60 s); progress and the final status line go to stderr, and --json prints the finished pipeline. A scheduled (delayed) job keeps it waiting. Exits 0 on success, 1 when it failed, was canceled or skipped, or stopped at a manual job (--manual-ok accepts that), and 8 when --timeout (default 60m) runs out. |
champrep code jobs ls PROJECT | List jobs, newest first, or one pipeline’s jobs with --pipeline ID. --status failed,running; --limit. |
champrep code jobs log PROJECT JOB_ID | Print a job’s log. --tail N prints the last N lines, read from the end of the log, so it works on a log of any size. --follow (-f) keeps printing until the job finishes; the closing “Job N finished” line goes to stderr, so stdout holds only the log, and the exit code is the job’s outcome: 0 when it succeeded, 1 when it failed or was canceled. A log larger than 8 MiB needs --tail or --follow, which then starts from its last 100 lines. |
champrep code jobs play PROJECT JOB_ID | Start a manual job. --var KEY=VALUE passes a job variable. |
champrep code jobs retry PROJECT JOB_ID | Retry a finished job. |
Runners
Section titled “Runners”runners also accepts runner.
| Command | Purpose |
|---|---|
champrep code runners ls | List the project and group runners you manage. --project PROJECT (runners the project can use; Maintainer), --group GROUP (Owner), --all (instance administrators). Filters: --status online|offline|stale|never_contacted, --paused / --active, --tag a,b, --type instance|group|project, --search, --limit. |
champrep code runners show RUNNER_ID | Show status, online, paused, tags, last contact, machines, and assigned projects or groups. |
champrep code runners update RUNNER_ID | --tags a,b replaces the tag list; --add-tag / --remove-tag (repeatable) change it by reading the tags and writing the whole list back, so a change someone makes in between is overwritten; --pause / --resume; --description. |
champrep code runners create | Create a project runner (--project, Maintainer) or a group runner (--group, Owner). Also --description, --tags, --no-untagged, --protected, --locked, --paused. Prints the runner authentication token (ccrt_…) once on stdout and never logs it. Always needs --yes. Alias register. |
Connect a machine to a new runner with
champrep-code-runner register.
Resetting a runner token and creating instance runners stay in the web app.
Releases
Section titled “Releases”| Command | Purpose |
|---|---|
champrep code releases ls PROJECT | List releases, newest first. --limit. |
Lists show 20 rows by default. Raise --limit (up to 500) to see more; the
CLI says so when more rows exist, and at --limit 500 it asks you to narrow
the filters instead. jobs ls --pipeline ID --status S filters on your side
after reading the pipeline’s first 500 jobs, and says when more may exist.
Examples
Section titled “Examples”More task-by-task recipes, with scripting variants, are in Common tasks.
Clone a whole group, with its subgroups, and keep it up to date:
champrep code clone --group acme --include-subgroups --dest ~/src --sshchamprep code clone --group acme --include-subgroups --dest ~/src --ssh --updateClone a project and open a merge request for your branch:
git clone "$(champrep code repo clone-url acme/web)"champrep code mr create acme/web --source feature/login --target main \ --title "Add login page" --remove-source-branch --yesReview open merge requests and merge one when its pipeline passes:
champrep code mr ls acme/webchamprep code mr show acme/web 12champrep code mr merge acme/web 12 --auto --squash --yesRun a pipeline, wait for it, and follow a job’s log:
champrep code pipelines run acme/web --ref main --var DEPLOY=staging --yeschamprep code pipelines wait acme/web --ref main && echo "main is green"champrep code pipelines ls acme/web --ref main --limit 5champrep code pipelines show acme/web 9921champrep code jobs log acme/web 4182 --followFind failed jobs and retry one:
champrep code jobs ls acme/web --status failedchamprep code jobs log acme/web 4180 --tail 50champrep code jobs retry acme/web 4180 --yesTrack issues:
champrep code issues ls acme/web --labels bug --search loginchamprep code issues create acme/web --title "Login fails on Safari" --labels bug,webchamprep code issues close acme/web 34 --yesConfirmation and scripting
Section titled “Confirmation and scripting”Commands that change something important ask before they act: mr create
(opening a merge request can start a pipeline), mr merge, mr approve,
issues close and reopen, runners update, and every pipeline and job
action (run, retry, cancel, play), which use CI minutes.
runners create always needs --yes, also on a terminal, because it prints
a credential. clone changes only your disk and does not ask. On a terminal, answer y.
In a script, pass --yes (-y). Without a terminal and without --yes the
command refuses and changes nothing.
Creating a project or an issue does not ask. Creates, merges, pipeline runs, retries and cancels, and job plays and retries carry an idempotency key, so the CLI’s automatic retry after a network error never does the work twice.
The CLI refuses a project, merge request, issue, pipeline or job argument with
a . or .. path segment before sending anything.
Add --json to print what Code returned: lists print a JSON array of items,
pipelines show prints { "pipeline": …, "jobs": [ … ] }.
champrep code mr ls acme/web --json | jq -r '.[] | "\(.iid) \(.title)"'Errors you may see
Section titled “Errors you may see”| Message | What to do |
|---|---|
needs your web session … (SESSION_REQUIRED) | Merging or approving into a protected branch is a decision only you can take, signed in to the CHAMPREP Code web app. Open the merge request in your browser and merge or approve it there. Unprotected branches work from the CLI. |
not allowed for your role … (MERGE_NOT_ALLOWED), (PROJECT_ARCHIVED) | Your role in the project does not allow the action, or the project is archived (read-only). Ask a Maintainer or Owner. |
not available to your account … | Your plan or organization policy does not include CHAMPREP Code or this feature. See plans or ask your administrator. |
quota exceeded …, payment required … | Your plan’s capacity or CI minutes are used up. Add capacity in CHAMPREP Billing, then run the command again. |
not found … | The project, merge request, issue or pipeline does not exist, or you cannot see it. |
http 409 … (SHA_MISMATCH) | The merge request moved since you looked. Check mr show and try again. |
Exit codes follow the command reference: every
refusal above exits 1, including --json runs; 3 means you need to sign in
again, 5 a gateway rate limit, 6 a network failure and 7 a service
failure that retries did not get past. pipelines wait exits 1 when the
pipeline did not succeed and 8 when its --timeout ran out; jobs log --follow exits 1 when the job failed or was canceled. Both wait and retry on
their own through service errors, rate limits and network failures, and give
up after eight retries in a row.