Restricted Commands Documentation

This document describes all available restricted commands that require specific permissions to execute. These commands can be executed via GitHub issue or pull request comments using the @holdex bot.

Permission Requirements

Each command below specifies the required permission level. Permissions are checked based on:

Organization role: Requires the user to have a specific role (Administrator or Member) in the organization. The organization used for validation is either the organization explicitly specified in the command (for example, via an org argument) or, if not provided, the organization where the command is executed.
Repository permission: Requires the user to have a specific permission level (admin, maintain, write, triage, or read) in the repository. The repository used for validation is the repository provided in the command (for example, via a repository or owner/repo argument).

Permissions are automatically checked by the bot based on the GitHub user's actual role and permissions in the resolved organization or repository.

Command Format

All commands follow the pattern:

@holdex <object> <action> [arguments...]

Arguments can be provided as:

Flags: --key=value or --key="value with spaces"
Positional arguments: Some commands accept positional arguments (values without flags)

Available Commands

1. Org Add User

Adds a user to a GitHub organization with a specified role.

Access: Organization admin role required

Location: Issue and pull request comments

Command:

@holdex org add-user <username> | --username=<username> --role=<role> [--org=<org>]

Args Schema

Arguments:

Property	Type
`org`	`string`
`username` (*)	`string` (min length: 1)
`role` (*)	`'admin' \| 'member'`

(*) Required.

Example:

@holdex org add-user johndoe --org=holdex --role=member

2. Repo Apply Settings

Applies repository settings including visibility, branch protection, and merge settings.

Access: Repository admin permission required

Location: Issue and pull request comments

Command:

@holdex repo apply-settings <repo> | --repo=<repo> --visibility=<visibility> --deleteBranchOnMerge=<deleteBranchOnMerge> --allowUpdateBranch=<allowUpdateBranch>

Args Schema

Arguments:

Property	Type	Default
`repo` (*)	`string` (min length: 1)
`visibility` (*)	`'private' \| 'public'`
`deleteBranchOnMerge`	`string`	`'true'`
`allowUpdateBranch`	`string`	`'true'`

(*) Required.

Example:

@holdex repo apply-settings holdex/my-repo --visibility=private --deleteBranchOnMerge=true --allowUpdateBranch=true

3. Repo Sync Labels

Synchronizes issue types and labels for a repository according to the ledger configuration.

Access: Repository write permission required (also available with: admin, maintain)

Location: Issue and pull request comments

Command:

@holdex repo sync-labels <repo> | --repo=<repo>

Args Schema

Arguments:

Property	Type
`repo` (*)	`string` (min length: 1)

(*) Required.

Example:

@holdex repo sync-labels holdex/my-repo

4. Issue Request Kyc

Creates a Didit identity verification (KYC) session and posts the verification link as a GitHub issue comment.

Access: Organization admin role required (validated in organization holdex)

Location: Issue and pull request comments

Command:

@holdex issue request-kyc [<issueUrl> | --issueUrl=<issueUrl>] [--assigneeUsername=<assigneeUsername>]

Args Schema

Arguments:

Property	Type
`issueUrl`	`string`
`assigneeUsername`	`string`

All properties are optional.

Example:

@holdex issue request-kyc https://github.com/holdex/johndoe-hr/issues/1 --assigneeUsername=johndoe

5. Member Onboard

Onboards a new contractor to the GitHub HR system. Creates a private HR repository, README, invites the user, syncs labels, assigns the hr-onboarding team, and creates five sub-issues: HR Card, Identity Verification Problem, Agreement Problem, Social Profile Problem, and Salary. Also opens the Special Terms PR pre-filled with any supplied fields. Posts an onboarding comment with links to all issues. Any  placeholder from the Special Terms template can be passed as a flag (e.g. --newField=value) without a code change.

Access: Organization admin role required (validated in organization holdex)

Location: Issue and pull request comments

Command:

@holdex member onboard --firstname=<firstname> --lastname=<lastname> --githubUsername=<githubUsername> [--primaryCapacity=<primaryCapacity>] [--gmailEmail=<gmailEmail>] [--commencementDate=<commencementDate>] [--idNumber=<idNumber>] [--ratePerHour=<ratePerHour>] [--regAddress=<regAddress>] [--phoneNumber=<phoneNumber>] [--dateOfBirth=<dateOfBirth>]

Args Schema

Arguments:

Property	Type
`firstname` (*)	`string` (min length: 1)
`lastname` (*)	`string` (min length: 1)
`githubUsername` (*)	`string` (min length: 1)
`primaryCapacity`	`string`
`gmailEmail`	`string`
`commencementDate`	`string`
`idNumber`	`string`
`ratePerHour`	`string`
`regAddress`	`string`
`phoneNumber`	`string`
`dateOfBirth`	`string`

(*) Required.

Example:

@holdex member onboard --firstname=John --lastname=Doe --githubUsername=johndoe --gmailEmail=johndoe@gmail.com --commencementDate=01-Jan-2026

6. Client Onboard

Creates a private client-[name] repository from a Client card, seeds agreement and proposal files from the source repo, transfers issues, opens the Agreement Problem, configures the repo, and opens a lead deletion PR.

Optional --org records the client GitHub org in config.yaml and the README when Wizard can reach it; otherwise opens a Problem to install Wizard there.

Managers only.

Lead folder limits: each file must be ≤1 MB; total size of docs/leads/[name] must be ≤25 MB.

Fails if another lead file would also become docs/proposals/initial-proposal.md (e.g. an existing proposals/initial-proposal.md while --proposal points elsewhere).

Access: Holdex manager required (isManager: true in team-members config)

Location: Client card issue comments only (title starts with Client:)

Command:

@holdex client onboard <name> | --name=<name> --doc=<doc> --proposal=<proposal> [--org=<org>]

Args Schema

Arguments:

Property	Type
`name` (*)	`string` (min length: 1, regex: `/^[a-z0-9]+(?:-[a-z0-9]+)$/`*)
`doc` (*)	`string` (min length: 1)
`proposal` (*)	`string` (min length: 1)
`org`	`string` (min length: 1)

(*) Required.

Example:

@holdex client onboard amulet --doc=https://docs.google.com/document/d/abc123 --proposal=https://github.com/holdex/partners-pipeline/blob/main/docs/leads/amulet/proposals/amulet-proposal.md --org=amulet

Usage Notes

Command Execution Location: Each command has specific location restrictions (see individual command documentation above). Commands can be restricted to:
- Issue comments only: Cannot be executed in pull request comments
- Goal & draft goal issue comments only: Must be executed in a goal or draft goal issue (not a regular issue or pull request)
- Bug issue comments only: Must be executed in a bug issue (not a regular issue or pull request)
- Client card issue comments only: Must be executed on a Client card (issue title starts with Client:)
- Pull request comments only: Can only be executed in pull request comments
- Issue and pull request comments: Can be executed in both issue and pull request comments All commands require an organization context (they must be run in a repository that belongs to an organization).
Command Pattern: Commands must follow the exact pattern @holdex <object> <action> [arguments...]. The object and action are case-insensitive and will be normalized to lowercase.
Error Handling: If a command fails, the bot will post a comment with error details, including the specific error message to help with troubleshooting.
Success Indication: Successful commands will add a reaction to your comment:
- 👀 (eyes) reaction indicates the command was successfully parsed and triggered
- 🚀 (rocket) reaction indicates the command task completed successfully
Asynchronous Execution: Commands are executed asynchronously. After parsing and validation, the command is triggered and runs in the background. The initial reaction (👀) indicates the command was accepted, while the final reaction (🚀) indicates completion.
Positional Arguments: Some commands support positional arguments as a convenience - they can be used instead of flags for common parameters. Positional arguments are captured for arguments that don't start with --.
Default Values: Some optional parameters have default values. Check individual command documentation above for details. If a parameter is not provided and has no default, it will be omitted.
Value Formatting:
- Use quotes for values with spaces: --key="value with spaces" or --key='value with spaces'
- Values without spaces don't need quotes: --key=value
- Single or double quotes are supported
- Values are parsed exactly as provided (case-sensitive for values)
Code Fences: Commands inside fenced code blocks (```...```) are excluded and will not be executed. This prevents accidental execution when showing command examples in documentation or comments.