Parokhet
Request a demo
Documentation

The parokhet command

Parokhet works with plain git and with the parokhet command. The command handles repositories, pull requests, issues, CI runs, secrets, variables, tokens, releases and packages, and its commands follow gh closely. This page covers moving a team from GitHub and lists every command. Run parokhet help COMMAND for the full help of one command.

Install

The install script picks the file for your system from the release channel, checks its SHA-256 checksum and its Ed25519 signature, and then installs it. You do not need an account to run it.

macOS and Linux
$ curl -fsSL https://parokhet.siliconblast.com/install.sh | sh
Windows (PowerShell)
> irm https://parokhet.siliconblast.com/install.ps1 | iex

On macOS and Linux the script installs into ~/.local/bin when that folder is on your PATH, else into /usr/local/bin when you can write to it. On Windows it installs into %LOCALAPPDATA%\Parokhet\bin. Set PAROKHET_INSTALL_DIR to pick another folder.

After installing, the script checks which parokhet your shell runs. When another parokhet comes earlier on your PATH, it prints a warning with both paths, because typing parokhet would still run the old file. An old Python entry point left by an earlier Parokhet tool is a common cause. Remove the old file as the warning says, or put the install folder earlier in your PATH, then run parokhet --version to check.

To update later, run parokhet update. It checks the same hash and signature before it replaces itself. See update. To download a file by hand, use Downloads, which lists each file with its size, checksum and signature.

Sign in

parokhet login prints a code and opens the host's /cli/login page in your browser.

To sign in, open https://parokhet.siliconblast.com/cli/login and enter this code:
    QRTF-8842
Opening your browser. Waiting for approval...
  • Sign in on that page if the browser is not signed in yet.
  • Check the account the page shows. The CLI will act as that account. Use "Use a different account" to switch.
  • Type the code from the terminal and press Approve. The code expires after 10 minutes.

The CLI signs in only after you approve, even when the browser already has a session. It then gets its own forge token for this machine, named parokhet-cli-YYYYMMDD-xxxxxx, with no admin rights. The token is stored in the OS keychain (the macOS Keychain, the Windows Credential Manager, or the Secret Service on Linux). When no keychain is available, it is stored in ~/.parokhet/auth.json, which only you can read. The token is never printed.

The token expires after 30 days. Commands then say Your CLI sign-in expired or was revoked. Run parokhet login. and you sign in again. The CLI never makes a new token on its own. parokhet whoami shows the account and when the token expires.

On a machine with no browser, such as a server over SSH, run parokhet login --no-browser. It prints the same page and code and opens nothing. Open the page on any other device and approve there.

In CI and for agents, set PAROKHET_TOKEN to a forge token. Every command then uses it and nothing is stored. You can also store a token with parokhet login --token-file FILE (or - for stdin). Make a token for this with parokhet token create.

parokhet logout revokes the token on the host and removes it from this machine. A token added with --token-file is only removed from this machine.

$ parokhet login
$ parokhet login --no-browser
$ PAROKHET_TOKEN=<token> parokhet whoami
$ parokhet logout

Git remotes and credentials

Every Parokhet repository is a normal git repository. These are the remote URLs for OWNER/NAME on parokhet.siliconblast.com. parokhet repo view prints both for a repository.

https://parokhet.siliconblast.com/OWNER/NAME.git
HTTPS. Run parokhet auth setup-git once so git uses your sign-in.
git@parokhet.siliconblast.com:OWNER/NAME.git
SSH on port 22. Add your public key first with parokhet ssh-key add.

HTTPS with the credential helper

Run this once after parokhet login. It works like gh auth setup-git.

$ parokhet auth setup-git

It sets the global git config credential.https://parokhet.siliconblast.com.helper to the CLI, after an empty entry that clears any helpers already set for that host. From then on git clone, git fetch, git pull and git push over HTTPS get your forge login and token from the CLI. The token is never written into git's config. The helper answers nothing for other hosts. Run it again if you move the parokhet binary.

SSH keys

$ parokhet ssh-key add
$ parokhet ssh-key add ~/.ssh/work.pub --title "Work laptop"
$ parokhet ssh-key list
$ parokhet ssh-key delete ID

Without a file, ssh-key add uses the first of ~/.ssh/id_ed25519.pub, id_ecdsa.pub and id_rsa.pub that exists. These commands need the write:user scope. Tokens from sign-ins made before CLI 1.3.0 do not have it, so run parokhet login again before ssh-key add if you signed in with an older CLI.

You can also add keys in the web app. Open Settings, then SSH / GPG keys, and paste the public key.

Clone

$ git clone https://parokhet.siliconblast.com/acme/api.git
$ git clone git@parokhet.siliconblast.com:acme/api.git
$ parokhet repo clone acme/api
$ parokhet repo clone acme/api --ssh

Push an existing local repository

With the CLI, as with gh repo create --source . --push:

$ cd my-project
$ parokhet repo create my-project --source . --push

The new repository starts empty. The CLI adds a remote named origin (or the name in --remote) with the HTTPS URL, pushes the branch you have checked out, and sets it to track the remote. Add --org acme to create it in an organization.

With plain git, create an empty repository first (in the web app, or with parokhet repo create my-project --no-init), then add the remote and push:

$ git remote add origin https://parokhet.siliconblast.com/OWNER/my-project.git
$ git push -u origin main

To move an existing GitHub remote instead, run git remote set-url origin URL with the Parokhet URL. To bring over issues, pull requests and releases as well, use parokhet import.

Which repository a command uses

Every command that takes OWNER/NAME first can leave it out inside a clone, as with gh. The CLI picks the repository in this order:

  1. --repo OWNER/NAME, or -R OWNER/NAME.
  2. A first argument that contains /.
  3. The default set with parokhet repo set-default OWNER/NAME. It is stored in the clone's git config as parokhet.repo, so it applies to that clone only.
  4. The git remote whose URL points at the current host: origin first, then upstream, then the only remote that matches. HTTPS, git@HOST: and ssh:// URLs all count.

When nothing matches, the command stops with this message:

Error: No repository was given and none could be found. Run this inside a clone of a Parokhet repository, pass OWNER/NAME, or run parokhet repo set-default OWNER/NAME.

A first argument without / is never a repository. So parokhet run view 42 means run 42 of the current repository, and parokhet run view acme/api 42 also works. A release tag or workflow file name that contains / needs --repo when the repository is inferred.

$ parokhet repo set-default acme/api   # use acme/api in this clone
$ parokhet repo set-default            # print the default, or what would be used
$ parokhet repo set-default --unset

This applies to repo view, edit, delete, protect and runners, and to every pr, issue, run and release command. secret, var and promote use the clone's repository when you pass neither --repo nor --org. repo clone and repo create always need a name.

Coming from gh

Most gh commands have a parokhet command with the same shape. The repository flag is --repo or -R in both.

gh auth login
parokhet login
gh auth logout
parokhet logout
gh auth status
parokhet whoami
gh auth setup-git
parokhet auth setup-git
gh ssh-key add | list | delete
parokhet ssh-key add | list | delete
gh repo create NAME --source . --push
parokhet repo create NAME --source . --push
gh repo create ORG/NAME
parokhet repo create NAME --org ORG, or parokhet repo create ORG/NAME
gh repo clone | view | list | edit | delete
parokhet repo clone | view | list | edit | delete
gh repo set-default
parokhet repo set-default
gh pr create | list | view | checkout | diff
parokhet pr create | list | view | checkout | diff
gh pr review | comment | close | reopen
parokhet pr review | comment | close | reopen
gh pr checks
parokhet pr checks
gh pr merge --squash --delete-branch
parokhet pr merge NUMBER --squash --delete-branch. Add --wait to wait for required checks in the terminal.
gh issue create | list | view | comment | close
parokhet issue create | list | view | comment | close
gh run list | view
parokhet run list | view
gh run view --log | --log-failed
parokhet run view NUMBER --log | --log-failed
gh run watch
parokhet run tail
gh run rerun
parokhet run rerun. It reruns every job of a finished run, like the Re-run button. --failed reruns only the failed jobs, and --job NAME reruns one job.
gh run cancel
parokhet run cancel
gh workflow run WORKFLOW -f KEY=VALUE
parokhet run dispatch WORKFLOW --input KEY=VALUE
gh secret set | list | delete
parokhet secret set | list | delete
gh variable set | get | list | delete
parokhet var set | get | list | delete
gh release create | upload | download | list
parokhet release create | upload | download | list

parokhet github ARGS runs gh ARGS, so you can keep using gh against GitHub while you move.

Global flags

Global flags work before or after the command name.

--env NAME
The environment to use: dev, prod, or a name from parokhet config. The default is prod.
--host URL
A host URL to use instead of the environment's host.
--json
Print JSON.
-h, --help
Show help for a command.
-v, --version
Print the version.

CI workflows

CI on Parokhet is Forgejo Actions. Workflow files live in .forgejo/workflows/*.yml in the repository and use GitHub Actions YAML syntax. To move a GitHub workflow, copy it into that folder and check the points below.

Where jobs run

  • Jobs run on GitHub-hosted machines in a GitHub account or organization that you connect. Connect it in the web app at Settings, then GitHub runners, or run parokhet github connect. Use --org ORG for a Parokhet organization you own.
  • Each job checks the code out from Parokhet onto GitHub's temporary machine. Your code is never stored on GitHub.
  • Minutes are billed to the connected GitHub account. A job fails with a message when that account has no minutes left or is at its spending limit.
  • Each repository has a switch at its Settings, then GitHub runners, which is on by default. parokhet repo runners --on off turns it off, and jobs then wait. Without a connected account, jobs also wait.
  • parokhet repo runners --reuse on lets a job pass at once, without running, when the same job of the same workflow already passed on a commit with identical files. Its log names the run the result came from, and parokhet pr checks shows it. A rerun always runs the job. A reused job has no outputs, so leave this off if later jobs read a job's outputs.
  • parokhet github status shows which GitHub account runs the jobs for you and for each organization you own.

Triggers

push
Runs on pushes. Filter with branches, as on GitHub.
pull_request
Runs on pull requests. Its checks show in parokhet pr checks with names such as ci / test (pull_request), which is the name --require-check takes.
workflow_dispatch
Runs on request, with inputs. Start it with parokhet run dispatch WORKFLOW --input KEY=VALUE. parokhet promote also uses this trigger.
schedule
Runs on a cron timer.

runs-on labels

Each label maps to the GitHub-hosted image of the same name:

  • Linux: ubuntu-latest, ubuntu-24.04, ubuntu-22.04, ubuntu-24.04-arm, ubuntu-22.04-arm
  • macOS: macos-latest, macos-15, macos-14
  • Windows: windows-latest, windows-2025, windows-2022

The older Parokhet labels docker, supplychain and egress map to ubuntu-latest. A job with a label outside this list, or with labels that name two images, fails with a message that lists the labels.

What works in a job

  • Steps run with the tools that GitHub preinstalls on the image.
  • container: works. The job's steps run inside that image.
  • docker run, docker build and docker buildx build work, using the machine's Docker.
  • services: is skipped without an error, so the job runs with no service. Start service containers with docker run in a step instead, as in the example below.
  • Write step outputs and environment values to $GITHUB_OUTPUT, $GITHUB_ENV and $GITHUB_PATH (or the FORGEJO_ names). The old set-output, set-env and add-path workflow commands do not work.
    steps:
      - name: Start Redis
        run: |
          docker run -d --name pkredis -p 6379:6379 redis:7
          for i in $(seq 1 30); do nc -z localhost 6379 && break; sleep 1; done
      - run: go test ./...
        env:
          REDIS_URL: redis://localhost:6379

Actions in uses:

uses: OWNER/NAME@REF is fetched from github.com, the same as on GitHub. Any public action works, and nothing has to be mirrored first. To use an action from another host, give its full URL, such as uses: https://code.forgejo.org/actions/setup-forgejo@v2.

The host also keeps private backup mirrors of common actions. Workflows do not read them. See action.

Secrets and variables

A workflow reads a secret as ${{ secrets.NAME }} and a variable as ${{ vars.NAME }}. Set them with parokhet secret set and parokhet var set, on a repository or an organization. Secrets are masked in logs. Forgejo has no per-environment secrets, so name a per-environment value ENV__NAME, such as PROD__REGISTRY_TOKEN.

OIDC tokens

A job that sets enable-openid-connect: true gets ACTIONS_ID_TOKEN_REQUEST_URL and ACTIONS_ID_TOKEN_REQUEST_TOKEN, and requests a signed token the same way it would on GitHub. Configure your cloud provider to trust these values:

issuer
https://parokhet.siliconblast.com/api/actions. The discovery document is at /api/actions/.well-known/openid-configuration under the same host.
sub
repo:OWNER/NAME:ref:refs/heads/BRANCH
jobs:
  deploy:
    runs-on: ubuntu-latest
    enable-openid-connect: true
    steps:
      - run: |
          curl -fsS -H "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
            "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=sts.example.com" | jq -r .value > /tmp/id-token

A complete workflow

# .forgejo/workflows/ci.yml
name: ci
on:
  push:
    branches: [main]
  pull_request:
  workflow_dispatch:
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: go test ./...
        env:
          API_BASE: ${{ vars.API_BASE }}
          API_TOKEN: ${{ secrets.API_TOKEN }}

Push it, then follow the run from the terminal:

$ git add .forgejo/workflows/ci.yml && git commit -m "Add CI" && git push
$ parokhet run tail
$ parokhet run view NUMBER --log-failed

The pull request check from this file is named ci / test (pull_request).

Branch protection

$ parokhet repo protect --branch main --require-pr --approvals 1 \
    --require-check "ci / test (pull_request)" --dismiss-stale-approvals --apply-to-admins
--branch BRANCH
The branch to protect. Any branch works, such as main or qa.
--require-pr
Block direct pushes, so changes reach the branch only through merged pull requests.
--approvals N
A pull request needs N approving reviews before it can be merged. While N is above 0, a review that requests changes also blocks the merge. parokhet pr review NUMBER --approve counts toward N. The author of a pull request cannot approve it, so the approvals must come from other people. A repository or organization with only one person cannot use --approvals 1. Keep it at 0 there and rely on --require-pr and --require-check.
--require-check NAME
A status check that must pass, by name, such as "ci / test (pull_request)". Repeat it for more checks. parokhet pr checks shows the names a pull request reports.
--dismiss-stale-approvals
Drop approvals when new commits are pushed.
--apply-to-admins
Apply the rules to repository admins too.
--signed-commits
Reject unsigned commits.
--no-force-push, --no-deletion
A protected branch always refuses force pushes and deletion. Forgejo has no setting to allow them, so these are on and cannot be turned off.
--only-from BRANCH
Allow pull requests into the protected branch only from BRANCH, such as only qa into main. Forgejo has no setting for this, so the CLI turns on --require-pr and adds a required check named only-from / BRANCH (pull_request). A workflow in the repository must report that check.
--print-workflow
Print the workflow that reports the --only-from check, and change nothing.

Running the command again for the same branch replaces its rules with the flags you pass.

$ parokhet repo protect acme/api --branch main --only-from qa --print-workflow \
    > .forgejo/workflows/only-from-qa.yml
$ parokhet repo protect acme/api --branch main --only-from qa

Promote and environments

parokhet promote moves one built image from one environment to the next. The CLI runs checks on your machine and then starts a workflow in the repository, which does the copy on a runner. Registry credentials stay on the platform as secrets.

parokhet promote IMAGE@DIGEST --from ENV --to ENV [--repo OWNER/NAME]
Promote an image by digest from one environment to the next, after checks. A tag is refused, so the exact build that was tested is the one promoted. --repo defaults to the current clone.
$ parokhet promote registry.example.com/acme/api@sha256:3f1c... --from qa --to prod \
    --repo acme/api --commit 9b2e41d \
    --verify-key cosign.pub --require-ancestor main --require-passed ci.yml

Environments

An environment is only a name, such as qa, staging or prod. Parokhet keeps no list of environments and no settings per environment. --from and --to take any two different names, and the promote workflow decides what each name means, such as which registry path or which cluster. Name per-environment secrets ENV__NAME, such as PROD__REGISTRY_TOKEN, and pick one in the workflow from the to input.

The checks

They run in this order, and the first failure stops the promotion before anything starts. With no check flags, no checks run. --dry-run runs the checks and stops.

--verify-key FILE
Runs cosign verify --key FILE IMAGE on your machine. cosign must be installed.
--require-ancestor BRANCH
Passes when --commit is already on BRANCH, checked with the compare API. Needs --commit.
--require-passed WORKFLOW
Passes when a run of that workflow file, such as ci.yml, has the status success among the latest 50 runs for --commit. Needs --commit.

The promote workflow

When the checks pass, the CLI dispatches the workflow file named by --workflow (default promote.yml) on the branch named by --ref (default main). It receives these inputs:

  • image: the IMAGE@sha256:HEX you passed
  • from: the --from name
  • to: the --to name
  • commit: the --commit SHA, only when you passed --commit

Forgejo passes only the inputs the workflow declares, so declare all four:

# .forgejo/workflows/promote.yml
on:
  workflow_dispatch:
    inputs:
      image: { required: true }
      from: { required: true }
      to: { required: true }
      commit: { required: false }
jobs:
  promote:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Copy ${{ inputs.image }} from ${{ inputs.from }} to ${{ inputs.to }}"

Starting the workflow needs write access to the repository's Actions, so anyone who can push to that repository can promote.

Human approval

Forgejo has no GitHub-style environment protection rules. There is no way to require a reviewer before a deployment, and a dispatched workflow cannot pause for an approval. parokhet promote therefore cannot ask a person to approve. The supported pattern is to make the promotion a pull request and let branch protection require the approval:

  1. Keep the deployed digest for each environment in a file on a branch, such as deploy/prod on the branch prod, and have a workflow that runs on: push to prod do the copy.
  2. Protect that branch so a person must approve each change:
    $ parokhet repo protect acme/deploy --branch prod --require-pr --approvals 1 \
        --dismiss-stale-approvals --apply-to-admins
    To limit whose approval counts, turn on the approvals allowlist (users or teams) in the branch protection settings on the web page. The CLI does not set it.
  3. To promote, open a pull request that changes the digest, for example with parokhet pr create --base prod --title "Promote api to prod". It merges only after the required approvals and checks.

To gate the merge on the promote checks too, run parokhet promote --dry-run with your check flags in the promotion pull request's CI, and make that job a required check with --require-check. Another way to limit who can promote is to keep the promote workflow in a separate repository where only release managers have write access.

login, logout, whoami

parokhet login
Sign in to a Parokhet host. See Sign in. Flags: --no-browser (print the page and code without opening a browser), --paste (the same as --no-browser), --token-file FILE (read a forge token from this file, or - for stdin).
parokhet logout
Sign out of the current host. A token from parokhet login is revoked on the host and removed from this machine. A token added with --token-file is only removed from this machine.
parokhet whoami
Show the account you are signed in as.

auth

parokhet auth setup-git [--host URL]
Make git use the CLI's sign-in for HTTPS on this host. See Git remotes and credentials.

ssh-key

Manage the SSH keys on your account, for git over SSH. These commands need the write:user scope. Run parokhet login again if it is missing.

parokhet ssh-key add [PUBKEY_FILE] [--title TITLE]
Add an SSH public key to your account. The default file is the first of ~/.ssh/id_ed25519.pub, id_ecdsa.pub and id_rsa.pub that exists. The default title is <hostname> (parokhet).
parokhet ssh-key list
List the SSH keys on your account.
parokhet ssh-key delete ID
Delete an SSH key from your account. parokhet ssh-key list shows the IDs.

doctor

parokhet doctor
Check the CLI setup, the host, your session, your token's scopes, the release channel, and whether gh and glab are installed. It exits with status 1 when a required check fails.

guide

parokhet guide [--write FILE] [--force]
Print the agent guide, which tells a coding agent how to work with this host the way it would with GitHub and gh. --write FILE writes it to a file instead, and refuses to replace a file that exists unless you pass --force. The guide comes from the host, so its URLs match the host you use. Signed in to the web app, you can also read it, copy it and download it on the Agent guide page in your settings.
$ parokhet guide --write AGENTS.md

repo

Work with repositories. Commands that take OWNER/NAME find it on their own inside a clone. See Which repository a command uses.

parokhet repo list
List the repositories you can access. --limit (default 100).
parokhet repo view [OWNER/NAME]
Show a repository and its HTTPS and SSH clone URLs.
parokhet repo create NAME
Create a repository. New repositories are private unless you pass --public. A public repository is open to everyone, including people who are not signed in, even when its owner is a private organization or person. The owner's page, members and other repositories stay hidden. Flags: --org ORG, --public, --private, --description, --default-branch (default main), --no-init (no first commit), --source DIR, --remote (default origin), --push.
parokhet repo create NAME --org ORG
Create the repository in an organization. Naming it ORG/NAME does the same. You need permission to create repositories in that organization. It is private unless you pass --public.
parokhet repo create NAME --source . --push
Connect an existing local repository and push its current branch. See Git remotes and credentials.
parokhet repo edit [OWNER/NAME]
Change repository settings. Only the settings you pass are changed: --description, --website, --visibility, --default-branch and --topics.
parokhet repo edit [OWNER/NAME] --merge-styles STYLES
Set the allowed merge styles as a comma-separated list from merge, rebase, rebase-merge, squash and fast-forward-only. Styles you leave out are turned off. --default-merge-style STYLE sets the style the merge button starts with.
parokhet repo edit [OWNER/NAME] --delete-branch-after-merge=true
Delete the pull request branch after a merge by default. Pass =false to keep it.
parokhet repo edit [OWNER/NAME] --wiki=false
Turn the wiki on or off. --issues, --projects and --pull-requests work the same way.
parokhet repo delete [OWNER/NAME]
Delete a repository. This cannot be undone. Without --yes you must type OWNER/NAME to confirm.
parokhet repo clone OWNER/NAME [DIR]
Clone a repository with git. --ssh clones over SSH. Over HTTPS the token reaches git for this clone only and is not written into the repository.
parokhet repo set-default [OWNER/NAME]
Set the repository that commands use in this clone. Without an argument it prints the current default. --unset removes it.
parokhet repo protect [OWNER/NAME] --branch BRANCH
Set branch protection on any branch. See Branch protection.
parokhet repo runners [OWNER/NAME] [--on github|off] [--reuse on|off]
Show or change where a repository's CI jobs run, and whether a job reuses a passing result on identical files. See CI workflows.

org

Work with organizations. An organization owns repositories and has teams. A person is a member while they belong to at least one team, and the team sets what they can do. Every organization has an Owners team with full access. Creating organizations and changing members needs the write:organization scope. If the CLI says your token lacks it, run parokhet login again.

parokhet org create NAME
Create an organization and print its URL. You join its Owners team. Organizations are private unless you pass --visibility limited (visible to everyone signed in) or public. Flags: --full-name TEXT, --description TEXT, --visibility private|limited|public.
parokhet org list
List the organizations you belong to. --limit (default 100).
parokhet org view ORG
Show an organization with its visibility, URL, repositories and members.
parokhet org avatar ORG FILE
Set the organization's avatar from a PNG, JPEG, GIF or WebP image of at most 1 MiB and 4096x4096 pixels. A square image looks best. --remove removes the avatar instead. You must be an owner.
parokhet org member list ORG
List the members of an organization.
parokhet org member add ORG USERNAME --team TEAM
Add a person to an organization by adding them to the team you name. --owner adds them to the Owners team instead. With neither flag nothing is added and the command lists the organization's teams. You must be an owner.
parokhet org member remove ORG USERNAME
Remove a person from an organization and from all of its teams. You must be an owner.
parokhet org team list ORG
List the teams of an organization with their permission. Only members can see them.
parokhet org team create ORG NAME --permission read|write|admin
Create a team. read and write apply to the units in --units (default code,issues,pulls,releases,wiki,projects,packages,actions), and admin gives administrator access to every unit. --all-repos gives the team every repository in the organization. Without it the team starts with no repositories, and you add them under the team in the web app.
$ parokhet org create acme --full-name "Acme Inc"
$ parokhet org team create acme developers --permission write --all-repos
$ parokhet org member add acme alice --team developers
$ parokhet repo create api --org acme

Create an organization in the web app

  1. Open the + menu in the top bar and choose New organization. The page is at /org/create. The menu shows it only to accounts that may create organizations.
  2. Enter the organization name, choose the visibility, and choose Create organization. Organizations are private by default.
  3. Open the organization's Teams tab. To add someone with full access, open the Owners team, enter their username and choose Add team member.
  4. To give narrower access, choose New team. Pick Administrator access, or Custom access and set Read or Write for each unit. Choose All repositories or Specific repositories, create the team, and then add members to it the same way.

Change an organization's avatar in the web app

  1. Open the organization and choose Settings. You must be an owner.
  2. The Avatar section is at the top. Choose an image file, then Update avatar.
  3. Delete current avatar removes a picture you uploaded.

pr

Work with pull requests. Inside a clone, leave out OWNER/NAME.

$ git switch -c add-cache
$ git commit -am "Add a cache" && git push -u origin add-cache
$ parokhet pr create
$ parokhet pr checks 12
$ parokhet pr merge 12 --squash --wait --delete-branch
parokhet pr create [OWNER/NAME] [--title TITLE] [--head BRANCH]
Open a pull request. Push the branch first.
  • --base: the branch to merge into. The default is the repository's default branch.
  • --head: the branch with the changes. The default is the current branch.
  • --title: the default is the subject of the only commit when the head branch is exactly one commit ahead of the base. With more commits, pass --title.
  • --body TEXT or --body-file FILE: the description.
  • --draft: open it as a draft. Forgejo marks a draft by a title prefix, so the CLI puts WIP: in front of the title unless it already starts with WIP: or [WIP]. Forgejo will not merge a draft. Remove the prefix from the title when it is ready.
parokhet pr list [OWNER/NAME]
List pull requests. --state open|closed|all (default open), --author LOGIN, --limit (default 30).
parokhet pr view [OWNER/NAME] NUMBER
Show a pull request.
parokhet pr checkout [OWNER/NAME] NUMBER [--branch NAME]
Check out a pull request's branch in the current clone. The CLI fetches refs/pull/NUMBER/head into a local branch named after the head branch, or pr-NUMBER when that name is taken. When the branch exists, the CLI fast-forwards it.
parokhet pr diff [OWNER/NAME] NUMBER
Print a pull request's diff. --name-only prints only the paths of the changed files.
parokhet pr review [OWNER/NAME] NUMBER (--approve | --request-changes | --comment) [--body TEXT]
Approve a pull request, request changes, or leave a review comment. --request-changes and --comment need a body from --body or --body-file. Approvals count toward repo protect --approvals. Forgejo does not let the author approve their own pull request, so someone else has to review it.
parokhet pr comment [OWNER/NAME] NUMBER (--body TEXT | --body-file FILE)
Comment on a pull request.
parokhet pr close [OWNER/NAME] NUMBER
Close a pull request without merging it. --comment TEXT adds a comment before closing.
parokhet pr reopen [OWNER/NAME] NUMBER
Reopen a closed pull request.
parokhet pr checks [OWNER/NAME] NUMBER
Show the status checks on a pull request's latest commit. The names are the ones repo protect --require-check takes.
parokhet pr merge [OWNER/NAME] NUMBER
Merge a pull request.
  • --merge (the default), --squash or --rebase.
  • --wait: wait until every required check on the base branch has passed, and stop if one fails. When the base branch requires no checks, it waits for all reported checks. --timeout (default 30m).
  • --delete-branch: delete the head branch after the merge.
  • --message: the merge commit title.

issue

Work with issues. Inside a clone, leave out OWNER/NAME.

parokhet issue create [OWNER/NAME] --title TITLE
Open an issue. Flags: --body, --body-file, --label (repeatable).
parokhet issue list [OWNER/NAME]
List issues. --state open|closed|all (default open), --limit (default 30).
parokhet issue view [OWNER/NAME] NUMBER
Show an issue. --comments also shows the comments.
parokhet issue close [OWNER/NAME] NUMBER
Close an issue. --comment TEXT adds a comment before closing.
parokhet issue comment [OWNER/NAME] NUMBER --body TEXT
Comment on an issue or pull request. --body-file reads the comment from a file.

run

Work with CI runs. A run is named by its run number, the number in its web URL. Inside a clone, leave out OWNER/NAME.

parokhet run list [OWNER/NAME]
List recent runs. Filters: --workflow ci.yml, --status failure, --branch, --commit, --limit (default 20). It shows where the jobs ran when the host knows.
parokhet run view [OWNER/NAME] NUMBER [--log | --log-failed] [--job NAME_OR_ID]
Show one run, or print its job logs.
  • --log prints the log of every job, each under a line == job name ==.
  • --log-failed prints only the logs of the jobs that failed.
  • --job NAME_OR_ID prints one job, by name or ID, and turns on --log.
Each log is the job's latest attempt. A job that has not started has no log yet.
parokhet run tail [OWNER/NAME] [NUMBER]
Follow a run until it finishes. The default is the latest run. It exits with 0 on success, 1 on failure or cancel, and 2 when --timeout (default 30m) passes first. A run has finished only when every job has, so a run with one failed job and others still running shows running (1 failed) and tail keeps waiting. --status prints the status once.
parokhet run dispatch [OWNER/NAME] WORKFLOW
Start a workflow that has a workflow_dispatch trigger. Flags: --ref (default main), --input KEY=VALUE (repeatable).
parokhet run rerun [OWNER/NAME] NUMBER [--failed | --job NAME]
Run every job of a finished run again. This is the Re-run button on the run page. The run keeps its number, and its jobs start again as a new attempt with the same event, commit and inputs, so pull_request runs work too. --failed reruns only the jobs that failed or were cancelled, even while other jobs still run, and jobs that passed keep their result. --job NAME reruns one finished job. Jobs that need a rerun job start again after it. You need write access to the repository.
parokhet run cancel [OWNER/NAME] NUMBER
Cancel a run from the CLI. It waits up to --wait (default 10s) for the run to stop and prints the new status. You need write access to the repository. --web opens the run page instead, and --no-browser with --web prints its URL.
$ parokhet run list --status failure
$ parokhet run view 42 --log-failed
$ parokhet run view 42 --job test
$ parokhet run dispatch deploy.yml --ref main --input level=2
$ parokhet run cancel 42

secret

Manage Actions secrets for a repository (--repo OWNER/NAME) or an organization (--org ORG). Inside a clone, the default is the clone's repository. A workflow reads a secret as ${{ secrets.NAME }}. Values are never shown.

parokhet secret set [NAME [VALUE]] [--repo OWNER/NAME | --org ORG]
Create or update secrets. Give the value as an argument, with --from-file, or with --stdin. With none of these, the CLI asks for it. --env-file FILE sets one secret for each KEY=VALUE line.
parokhet secret list [--repo OWNER/NAME | --org ORG]
List secret names.
parokhet secret delete NAME [--repo OWNER/NAME | --org ORG]
Delete a secret.

var

Manage Actions variables for a repository (--repo OWNER/NAME) or an organization (--org ORG). Inside a clone, the default is the clone's repository. A workflow reads a variable as ${{ vars.NAME }}. Values can be read back and are not masked in logs.

parokhet var set [NAME VALUE] [--repo OWNER/NAME | --org ORG]
Create or update variables. --from-file, --stdin and --env-file FILE work as for secrets.
parokhet var get NAME [--repo OWNER/NAME | --org ORG]
Print a variable's value.
parokhet var list [--repo OWNER/NAME | --org ORG]
List variables and their values.
parokhet var delete NAME [--repo OWNER/NAME | --org ORG]
Delete a variable.

token

Manage scoped access tokens. These commands use the host's token API and work with your stored token or PAROKHET_TOKEN.

parokhet token create --name NAME --scope SCOPE...
Create a token. Its value is shown once. --scope is repeatable, for example read:repository. A name has 1 to 50 letters, digits, dots, dashes or underscores. Only a site admin can use all or an admin scope. Each account can create 10 tokens per hour.
parokhet token list
List your tokens with their scopes and last eight characters. Token values are never shown.
parokhet token revoke NAME|ID
Revoke a token by its name or ID.

runner

parokhet runner list [--repo OWNER/NAME | --org ORG | --admin]
List runners. The default is your own runners. --admin lists every runner on the host and needs an admin token. The runners for jobs on GitHub are made for one job each and removed when it ends. See CI workflows.

action

Workflows fetch uses: OWNER/NAME@REF from github.com, so no mirror is needed to use an action. These commands keep private backup mirrors of actions on the host, in system organizations that are hidden from dashboards and from anyone who is not signed in. Workflows do not read the mirrors.

parokhet action mirror OWNER/NAME[@REF]
Mirror a public action from github.com or code.forgejo.org. OWNER/NAME means github.com, and a full URL also works. The @REF part is ignored because the mirror holds every branch and tag. The host pulls new commits every 8 hours. Asking for a mirror that exists starts a sync. Each account can make 20 requests per day.
parokhet action list
List the mirrored actions with their upstream and last sync.

release

Work with repository releases and their files. Inside a clone, leave out OWNER/NAME.

parokhet release create [OWNER/NAME] --tag TAG
Create a release. The tag is created when it does not exist. Flags: --title, --notes, --notes-file, --target, --draft, --prerelease.
parokhet release upload [OWNER/NAME] TAG FILE...
Attach files to a release.
parokhet release download [OWNER/NAME] TAG
Download a release's files. --pattern picks files by glob and --dir sets the folder.
parokhet release list [OWNER/NAME]
List releases.
https://HOST/OWNER/NAME/releases/download/TAG/FILE
A download link for one file of one release. It works in a browser or with curl.
https://HOST/OWNER/NAME/releases/latest/download/FILE
The same file from the latest release. The link stays the same when you publish a new version. Drafts and prereleases are never the latest.

People who are not signed in can use both links when the repository is public, whoever owns it. Otherwise the link needs a signed-in browser or a token, as in curl -fL -H "Authorization: token $TOKEN" URL.

registry

Sign in to the package registries on the host. It serves a container registry and npm, PyPI and Cargo registries, and each one accepts your forge token as the password.

parokhet registry login [docker|npm|pypi|cargo]
Print the login steps for a registry. The default is docker. --run runs them for docker, npm and cargo. --owner picks the user or organization that owns the packages.
parokhet registry token
Print your forge token for a registry login command, such as parokhet registry token | docker login HOST -u USER --password-stdin.

import

parokhet import github|gitlab OWNER/REPO
Import a repository from GitHub or GitLab. The import runs on the host and the CLI prints each step until it finishes. --with picks from code, issues, pull_requests, releases, wiki, labels, milestones, lfs, pipelines and secrets. The default is everything except secrets. --to picks the user or organization to import into. The new repository is private unless you pass --public.
$ parokhet import github octo/widgets --to acme --with code,issues,pull_requests
$ parokhet import gitlab group/app --gitlab-url https://gitlab.example.com --public

The source token comes from --source-token, then GITHUB_TOKEN or GH_TOKEN (or GITLAB_TOKEN), then gh auth token or glab auth token when those tools are installed. You can also import in the browser at /import.

echo

Echo adds one empty commit to a GitHub repository of yours for each commit you push to Parokhet. The empty commits carry the original date and the message "Parokhet activity". They contain no files, no code and no repository names.

parokhet echo status
Show your Echo settings.
parokhet echo enable --to OWNER/REPO
Turn Echo on for a GitHub repository. Flags: --email, --github-token.
parokhet echo disable
Turn Echo off and delete the stored GitHub token.

github

parokhet github [ARGS...]
Run the GitHub CLI (gh) with the arguments.
parokhet github connect [--org NAME]
Connect your GitHub account so CI jobs run there. It opens the GitHub runners settings page. --org connects a Parokhet organization that you own. --no-browser prints the URL.
parokhet github status
Show which GitHub accounts run your CI jobs.
parokhet github repos
List your GitHub repositories to pick an import source. Flags: --token, --limit.

gitlab

parokhet gitlab [ARGS...]
Run the GitLab CLI (glab) with the arguments.
parokhet gitlab repos
List your GitLab projects to pick an import source. Flags: --token, --limit, --gitlab-url.

config

Read and change CLI settings. The keys are env and hosts.ENV.

parokhet config get KEY
Print one setting.
parokhet config set KEY VALUE
Change one setting. An empty host value removes a custom environment.
parokhet config list
Print every setting.

update, version

parokhet update
Install the latest signed CLI from the current host's release channel. The CLI checks the SHA-256 hash and the Ed25519 signature with the release key built into it, and replaces itself only when both pass. --check only reports whether an update is available. --force installs the channel's version even when it is not newer.
parokhet version
Print the CLI version.

completion

parokhet completion bash|zsh|fish|powershell
Print a shell completion script.
$ parokhet completion zsh > "${fpath[1]}/_parokhet"

Environment variables

PAROKHET_TOKEN
A forge token to use for every command instead of the stored session. Nothing is stored.
PAROKHET_ENV
The environment to use, like --env.
PAROKHET_HOST
The host URL to use, like --host.
PAROKHET_HOME
The folder for settings and credentials. The default is ~/.parokhet.
PAROKHET_INSTALL_DIR
The folder the install scripts install into.