Skip to content
AppraiseJS AppraiseJS

Install Template Steps with CLI

Advanced operations

Use the `appraisejs` CLI when you want to pull a published template step into an existing AppraiseJS project instead of writing that step from scratch in the UI.

Role: maintainers and advanced authorsInput: registry step slugOutcome: local step file updated and synced
Open Template Steps Open Sync and Scripts

Before you begin

Section titled “Before you begin”
  • Use Node.js 18 or later.
  • Run the command inside an existing AppraiseJS scaffold, or pass `--cwd` to that project.
  • Install project dependencies first so `node_modules` exists.
  • Make sure the target project already includes `scripts/install-template-step.ts`, `appraisejs:install-step`, `sync-template-step-groups`, and `sync-template-steps`.

Basic command

Section titled “Basic command”
Terminal window
npx appraisejs@latest add step <group-slug>/<step-slug>

Examples:

Terminal window
npx appraisejs@latest add step click/double-click
npx appraisejs@latest add step input/select-dropdown-option
npx appraisejs@latest add step navigation/go-back

The slug comes from the published step registry. It is built from the step-group slug plus the step slug, for example click/double-click.

What the command does

Section titled “What the command does”
  1. Validates that the target directory is a compatible AppraiseJS project.
  2. Resolves the registry manifest, then downloads the requested step fragment.
  3. Verifies the downloaded fragment checksum before installing anything.
  4. Merges the step into the correct local group file under automation/steps.
  5. Runs sync-template-step-groups and sync-template-steps if the install changed the project.

Result

The installed step becomes part of your local automation workspace and then appears in the AppraiseJS UI after sync completes.

Where files are written

Section titled “Where files are written”

The installer chooses the target file from the published group metadata:

  • Action groups go to automation/steps/actions/*.step.ts.
  • Validation groups go to automation/steps/validations/*.step.ts.
  • Missing group files are created automatically.

Examples:

  • click/double-click installs into automation/steps/actions/click.step.ts
  • active-state-assertion/assert-element-active installs into automation/steps/validations/active_state_assertion.step.ts

When a group file already exists, the installer preserves existing non-runtime imports and surrounding notes, ensures the required runtime imports are present, and appends or replaces the step definition inside that file.

Flags

Section titled “Flags”
Terminal window
npx appraisejs@latest add step <group-slug>/<step-slug> \
  --cwd /path/to/project \
  --overwrite \
  --dry-run \
  --registry-url https://example.com/registry/template-steps \
  --branch main
  • --cwd <path> targets a different AppraiseJS project directory.
  • --overwrite replaces an existing step when the same signature already exists with different code in the same group file.
  • --dry-run prints the install result and target file without writing files or running sync.
  • --registry-url <url> overrides the default registry and accepts either a manifest.json URL or a registry base URL.
  • --branch <ref> fetches the public GitHub registry from a specific branch instead of using the bundled registry shipped with the package.

Conflict and safety rules

Section titled “Conflict and safety rules”
  • If the exact same step is already installed, the command no-ops.
  • If the same signature exists in another local step file with different code, installation fails instead of guessing which implementation should win.
  • If the target group name already exists in the opposite folder type, installation fails. Example: an action group named click cannot be installed while a validation group file with that same normalized name already exists.
  • --overwrite only helps when the conflicting signature is in the target group file. It does not override cross-file conflicts.

Common failure cases

Section titled “Common failure cases”
  • No package.json found: --cwd points at the wrong directory.
  • Missing appraisejs:install-step or sync scripts: the target project scaffold is too old for this feature.
  • Dependencies are not installed: run your package manager install first.
  • Step "<slug>" was not found in the registry manifest: the slug is wrong or the selected registry source does not publish it.
  • Checksum mismatch or request failure: the registry content is unavailable or inconsistent. Retry or switch to a known-good registry source.

When to use this instead of the UI

Section titled “When to use this instead of the UI”
  • Use the UI when you are authoring a project-specific custom step from scratch.
  • Use the CLI when you want a published reusable step merged into the project quickly and consistently.

Next step

Section titled “Next step”