Skip to content

CLI reference ​

npx projectops is the only official way to install and update workflows, issue and PR templates, and Agent Skills in an existing project. All you need is Node.js 20.12 or later; it runs without a separate install (macOS, Linux and Windows). The source of truth for flags is npx projectops --help.

At a glance ​

You want toRun
Install by answering questionsnpx projectops
Install in one line, without questionsnpx projectops --mode full --type spring --force
Install Agent Skills onlynpx projectops --mode skills
Check the install state (read-only)npx projectops --mode doctor
See every option at once (JSON for AI agents)npx projectops --mode options --json

Interactive wizard ​

Run npx projectops in your project folder. This is a real run on a sample Spring project.

npx projectops interactive wizard

The wizard asks in this order. Most defaults are the recommended values, so pressing Enter is usually enough.

StepQuestionWhat it decides
1What would you like to install?Full install, version control, workflows, issue and PR templates, or AI skills
2(automatic) Project detectionFinds the type (spring, flutter, react, etc.), version and branches from marker files such as build.gradle and pubspec.yaml
3Choose the project kindFewer follow-up questions depending on whether you deploy a server or app, or publish a library
4Choose how to deploy the runnableDocker + SSH server deployment (default), Vercel, or no deployment
5Choose the PR comment modeChange summary, code review (CodeRabbit), both, or none
6Development (release source) branchThe branch that collects development and is raised to the default branch (default develop). If it does not exist, the wizard offers to create it and push it to the remote
7Secret server backupWhether to include the Secret server backup workflow
8Deployment environment valuesService name, domain, JDK version, etc. You can choose "Install everything with the defaults above"
9AI agent skillsWhether to also install them for Claude Code, Cursor, Gemini CLI, Codex CLI and PI

Every selected value is stored in metadata.template.options.* of version.yml, so the next run (update) does not ask again.

One-line run (non-interactive) ​

In CI or scripts, --force skips every confirmation and uses the defaults. A typical flow is to install, then check the state with --mode doctor.

One-shot install and doctor

bash
npx projectops --mode full --type spring,react --force
npx projectops --mode workflows --type flutter --paths "flutter=app"
npx projectops --deploy docker-ssh --publish nexus,npm
npx projectops --intent library

Modes ​

The --mode value decides what to install. Without it, the CLI runs interactively.

ModeWhat it does
fullFull integration: workflows + version.yml + issue and PR templates + Skills
versionversion.yml only
workflowsWorkflows only
issuesIssue and PR templates only
skillsAgent Skills only
doctorDiagnose the integration state and repository settings (read-only, changes nothing)
optionsPrint every flag and every version.yml key with allowed values and defaults. Add --json for AI agents (read-only, no network)

Options ​

OptionDescription
-m, --mode MODEOne of the modes above. Default is interactive
-t, --type CSVProject types, e.g. spring,react,python. Supported: spring flutter react react-native react-native-expo node python basic (next was merged into react; use react for Next.js)
--project-version VInitial version of the target (e.g. 1.0.0). Auto-detected if omitted
--paths "t=p,..."Per-type project paths (monorepo), e.g. flutter=app,react=client
--intent KINDProject kind: app library both none manual. If omitted, inferred from --deploy/--publish. library/none skip the deploy question, and app/none skip the publish question
--deploy TARGETDeployment, pick one: docker-ssh (default) vercel none
--publish CSVPublish targets: nexus,npm,github-packages (default: none)
--deploy-branch NAMEHead branch of the release PR (default develop). It is separate from the default (deployment) branch
--deploy-trigger-branch NAMEBranch whose push runs the deploy workflows. Set it only when it differs from the default branch (default: the default branch)
--create-development-branchNon-interactive runs: create the development branch from the default branch and push it to origin when it is missing. Does nothing if it exists. The push never asks for credentials, so a remote that needs a login fails at once instead of waiting; a failed push does not fail the run and the summary prints the command to run yourself (default: off)
--secret-backup / --no-secret-backupInclude or exclude the Secret backup workflow
--ai-summary / --no-ai-summaryInclude or exclude the PR change summary workflow
--coderabbit / --no-coderabbitInstall the CodeRabbit PR code review config (.coderabbit.yaml), --mode full only. Needs the CodeRabbit GitHub app; an existing file is backed up as .bak and overwritten. Off when omitted (kept on if version.yml already stores on). Unrelated to release notes
--projects-sync / --no-projects-syncInclude or exclude the GitHub Projects status sync workflow (excluded for new installs, kept if already installed)
--ci-minutes-saver / --no-ci-minutes-saverSave Actions minutes in private repos: CI runs on PRs only and skips docs-only changes; the iOS build and Secret backup run only on manual dispatch (default: off)
--language LANGLanguage of the issue/PR templates and bot messages written into your repo: en ko. New installs en; existing installs keep the stored value (ko if none)
--label-style STYLEStatus label names: en (status: todo) or ko (legacy 작업전). New installs en
--lang LANGLanguage of the CLI screen: en ko. Not the same as the language written into the repo (--language). Defaults to the system language, en in CI and with --force
--remove-legacyRename retired old-generation deployment workflows to .bak (default: only list them with delete commands)
--jsonWith --mode options: JSON output for machines rather than people
--force, -y, --yesSkip all confirmations and use non-interactive defaults
-v, --versionPrint the projectops version
-h, --helpShow help

--nexus and --npm-publish (and --no-nexus, --no-npm-publish) are no longer used. Use --publish nexus and --publish npm instead.

Mobile app types (flutter, react-native, react-native-expo) already include the store deployment workflows, so the deploy and publish questions are skipped entirely. For the detailed rules, see the NPX wizard guide.

Full option reference ​

Every flag and every version.yml key, with values and defaults. This section is generated from src/core/options-schema.js, the same source as npx projectops --mode options --json. After changing that file, run node scripts/build_options_reference.mjs to refresh it.

CLI flags ​

Flagversion.yml keyValues / defaultDescription
-m, --mode MODEvalues: interactive full version workflows issues skills doctor options; default: interactiveWhat to do. Agents and CI should always pass an explicit non-interactive mode together with --force.
-t, --type CSVvalues: spring flutter react react-native react-native-expo node python basic; default: auto-detectedProject types, comma separated. The first one is the primary type.
--project-version VERSIONdefault: auto-detectedInitial version of the target project (x.y.z).
--paths type=path,...project_pathsdefault: repo rootPer-type project folders for monorepos, e.g. flutter=app,react=client.
--intent KINDmetadata.template.options.intentvalues: app library both none manual; default: inferred from --deploy/--publishProject kind. Decides whether deploy and publish questions are asked.
--deploy TARGETmetadata.template.options.deployvalues: docker-ssh vercel none; default: docker-sshWhere the app is deployed. Pick one.
--publish CSVmetadata.template.options.publishvalues: nexus npm github-packages; default: noneRegistries a library is published to. Several allowed.
--deploy-branch NAMEmetadata.development_branchdefault: developDevelopment branch: the head of the release PR. Not the repository default branch.
--deploy-trigger-branch NAMEmetadata.template.options.deploy_trigger_branchdefault: the default branchBranch whose push runs the deploy workflows. Only when it differs from the default branch.
--create-development-branchdefault: offNon-interactive runs: create the development branch from the default branch and push it to origin when it does not exist.
--language LANGmetadata.template.options.languagevalues: en ko; default: en for new installs, ko for existing installsLanguage of issue/PR templates and bot messages written into the repo.
--label-style STYLEmetadata.template.options.label_stylevalues: en ko; default: en for new installs, ko for existing installsStatus label names: en = 'status: todo', ko = legacy Korean names.
--secret-backup, --no-secret-backupmetadata.template.options.secret_backupdefault: excludedInclude / exclude the workflow that uploads GitHub Secrets to a server over SSH.
--ai-summary, --no-ai-summarymetadata.template.options.code_review.ai_summarydefault: includedInclude / exclude the workflow that comments an AI summary on work PRs.
--coderabbit, --no-coderabbitmetadata.template.options.code_review.coderabbitdefault: off unless version.yml already says onInstall the CodeRabbit code review config (.coderabbit.yaml). Only --mode full installs it.
--projects-sync, --no-projects-syncmetadata.template.options.projects_syncdefault: excluded for new installs; kept if already installedInclude / exclude the GitHub Projects status sync workflow. Needs a PAT secret and PROJECT_URL variable.
--ci-minutes-saver, --no-ci-minutes-savermetadata.template.options.ci_minutes_saverdefault: offCut GitHub Actions minutes for private repos: CI runs on PRs only and skips docs-only changes, the iOS (macOS) CI build runs only on manual dispatch, secret backup runs only on manual dispatch.
--remove-legacydefault: offRename retired old-generation workflows to .bak. Without it they are only listed in the summary and in doctor.
-y, --yes, --forcedefault: offSkip every confirmation and use non-interactive defaults. Required for agents and CI.
--lang LANGvalues: en ko; default: system language; pinned to en in CI and with --forceLanguage of the CLI screen. Not the language written into the repo (that is --language).
--jsondefault: offWith --mode options: print machine-readable JSON instead of a table.
-v, --versionPrint the projectops package version and exit.
-h, --helpPrint the human-readable help and exit.
--nexus, --no-nexus(deprecated) Use --publish nexus. Also implies --deploy none.
--npm-publish, --no-npm-publish(deprecated) Use --publish npm.

version.yml keys ​

KeyTypeValues / defaultSet byDescription
versionstringworkflow-managedProject version (x.y.z). The single source of truth; workflows sync it into build files.
version_codeintegerworkflow-managedApp build number. +1 on every release. Android release only; iOS and test builds use build_number.py.
project_typesstring[]wizardProject types; the first is primary. Do not change after setup.
project_pathsmapwizard (--paths)Per-type project folder relative to the repo root (monorepo).
metadata.default_branchstringdefault: mainwizardRepository default (production) branch. Pushes here deploy.
metadata.development_branchstringdefault: developwizard (--deploy-branch)Development branch: head of the release PR. Old name deploy_branch is still read and written with the same value.
metadata.template.options.intentenumvalues: app library both none manualwizard (--intent)Project kind; derives the deploy and publish questions.
metadata.template.options.deployenumvalues: docker-ssh vercel none; default: docker-sshwizard (--deploy)Where the app is deployed.
metadata.template.options.publishenum[]values: nexus npm github-packages; default: []wizard (--publish)Library registries.
metadata.template.options.secret_backupbooleandefault: falsewizard (--secret-backup)Secret-to-server upload workflow installed.
metadata.template.options.semver_autobooleandefault: trueby handDecide the release bump from commit titles: 'type!:' = major, 'feat:' = minor, anything else = patch. Applies both to the release PR and to direct pushes to the default branch.
metadata.template.options.close_on_releasebooleandefault: true for new installs; missing for existing installsby handA release merge closes issues that carry the done label and are referenced by a release commit.
metadata.template.options.languageenumvalues: en kowizard (--language)Issue/PR template and bot message language.
metadata.template.options.deploy_trigger_branchstringdefault: the default branchwizard (--deploy-trigger-branch)Branch whose push runs the deploy workflows (app store, server, package publish).
metadata.template.options.ci_minutes_saverbooleandefault: falsewizard (--ci-minutes-saver)Install the CI workflows in their Actions-minutes-saving form (PR-only CI, docs-only changes skipped, iOS CI build and secret backup on manual dispatch only).
metadata.template.options.label_styleenumvalues: en kowizard (--label-style)Status label names.
metadata.template.options.projects_syncbooleanwizard (--projects-sync)Projects status sync workflow installed.
metadata.template.options.app_releasebooleanby handReleases go through App Store / Play Store review. Release notes get a review warning banner. Never auto-enabled.
metadata.template.options.excluded_workflowsstring[]by handWorkflow file names the update must never install. Deleted files are also not restored; a copy is kept in .github/.projectops/incoming/.
metadata.template.options.store_localesstring[]by handStore release-note languages, first is the default (for example ["ko-KR", "en-US", "ja-JP", "zh-CN"]). Missing = one text for every store language, as before. Per-language text comes from store_notes in CHANGELOG.json; a language without text gets the default-language text (the stores reject an empty What's New).
metadata.template.options.store_locales_iosstring[]by handOnly when the App Store languages differ from store_locales: the App Store uses this list instead. fastlane deliver ACTIVATES every language folder the app version does not have yet, so a language the App Store listing lacks must not be in this list.
metadata.template.options.store_locales_playstring[]by handOnly when the Play languages differ from store_locales: Google Play uses this list instead.
metadata.template.options.code_review.coderabbitbooleanwizardCodeRabbit config installed.
metadata.template.options.code_review.ai_summarybooleandefault: truewizard (--ai-summary)AI PR summary workflow installed.
metadata.template.options.changelog.providerenumvalues: copilot coderabbit openai gemini claude groq mistral ollama commit; default: commitby handRelease note generator. 'commit' is free and always works; AI keys are picked up automatically when registered as secrets.
metadata.template.options.changelog.base_urlstringby handOnly for provider ollama.

Diagnosis: doctor ​

--mode doctor writes no files and only checks the state.

  • Whether the template is installed in this folder, and how many workflows are installed
  • Whether any unreplaced values (placeholders such as __APPLICATION_YML_DIR__) remain that would fail at deploy time
  • The Secrets required by the installed workflows
  • Whether the workflows declare permissions

If you pass the GITHUB_TOKEN environment variable, it also checks repository settings (permissions, merge methods, Secrets).

bash
GITHUB_TOKEN=ghp_... npx projectops --mode doctor

Running again (update) ​

Running it again in a project that is already integrated works as an update.

  • Workflows you changed are not overwritten. They are skipped, the new template is saved in .github/.projectops/incoming/, and the CLI shows a command to compare them.
  • A run record is kept. Logs, events and a migration guide accumulate in .github/.projectops/logs/, and this folder is excluded from git tracking automatically. If something goes wrong, ask your AI agent to "check the run log".
  • Old workflows that were renamed are cleaned up automatically. For the detailed policy, see the migration section of the NPX wizard guide.

The old template_integrator.sh / .ps1 reached end of support and were removed from the repository. Use npx projectops. (Details)