CLI reference

The craftr command is the API Craft CLI (npm install -g @apicrafthq/cli). It runs the same core as the desktop app against the same project files, so anything you do in the GUI can be scripted.

Every command prints JSON: colorized on a terminal, plain when piped (so | jq works without a flag). Most commands accept --api/-a to pick the API when a project has more than one.

Pick a command below for its flags and examples, or filter to find it by name.

48 commands

craftr project

Create and validate an API Craft project.

  • project initInitialize an API Craft project in the current directory.
  • project validateValidate the project structure and report problems.
  • project trustApprove this project so its scripts (middlewares, custom auth, workflow scripts) can run. Persists until untrusted.
  • project untrustRefuse this project, blocking its scripts until it is trusted again.

craftr api

Manage APIs and their default auth and overrides.

craftr schema

Import an OpenAPI spec and manage the resource/operation mapping.

  • schema importImport an OpenAPI spec: preview the diff, resolve conflicts, write, and remap. Source may be a file path or URL; omit to use the saved source or piped stdin.
  • schema diffPreview the diff between the current schema and a candidate spec. Uses the persisted source if no path is given.
  • schema readRead the effective schema (resources, unmapped, ignored, orphan rules).
  • schema unmappedList operations that are not mapped to any resource.
  • schema ignoredList ignored operations with their rule ids.
  • schema mapMap an unmapped operation to a resource and operation name.
  • schema map-allBulk-map every unmapped operation. Choose exactly one mode.
  • schema rename operationRename a single operation within a resource.
  • schema rename resourceRename a resource.
  • schema set-parentSet or clear the parent of a resource. Provide a parent or pass --clear, not both.
  • schema ignoreIgnore an operation. It is removed from the effective schema.
  • schema unignoreRemove an ignore rule by operationId.
  • schema defineDefine a local operation that does not exist in the source spec. Creates the resource if new.
  • schema undefineDelete a locally-defined operation.

craftr spec

Read the OpenAPI spec.

  • spec readPrint the effective OpenAPI spec, or the raw imported spec with --imported.

craftr req

List, run, and manage request instances.

  • req listList request instances, optionally filtered.
  • req runExecute a request instance against an environment. Prints the response body by default.
  • req duplicateDuplicate a request instance. The copy is created as private.
  • req renameRename a request instance.
  • req set-visibilityChange a request instance's visibility (public or private).

craftr env

Manage environments and their values.

  • env listList environments.
  • env readRead an environment's values, with the extends chain resolved.
  • env writeWrite a single environment variable. The value is JSON-parsed if it is a valid scalar, otherwise stored as a string.
  • env deleteDelete an environment.
  • env renameRename an environment.

craftr workflow

Run project-scoped workflows.

  • workflow runRun one or more workflows (or every workflow with --all) and aggregate the results. Prints a JSON summary report on stdout, a human summary on stderr, and exits 1 if any workflow failed (130 if cancelled).
  • workflow listList every workflow in the project.
  • workflow validateCheck that a workflow's references resolve (api, resource, operation, instance, scripts) and refresh the generated script typings. Omit the name to check every workflow. Sends no request, so it is cheap to run in CI before a run.
  • workflow historyList past workflow runs newest first, or read one run in full by id. Run ids are the ISO timestamp of the run with ":" replaced by "-".
  • workflow renameRename a workflow, its scripts directory included.
  • workflow duplicateDuplicate a workflow, its scripts directory included.
  • workflow deleteDelete a workflow and its scripts directory.

craftr license

Install, inspect or remove the Pro license. Per user, not per project, so these work from any directory.

  • license installInstall a license from a file or from stdin. Verifies the signature first; on failure the current license, if any, is left in place.
  • license getPrint the active license state as JSON: status, tier, who it is issued to, expiry, features and limits. A limit of -1 means unlimited.
  • license removeDelete the installed license and fall back to the Free plan. Prints the resulting state.

craftr completion

Shell tab-completion management.

  • completion installInstall shell tab-completion. Writes the completion script and, for bash and zsh, adds a marked block to the shell rc file that sources it.
  • completion uninstallRemove the completion script and the block it added to the shell rc file.