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.

55 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 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 mapMap an unmapped operation to a resource and operation name.
  • 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.
  • schema map-allBulk-map every unmapped operation. Choose exactly one mode.

craftr import

Create an API from captured traffic or a collection.

  • import har planPreview what a HAR import would create: resources, operations, requests and the secret candidates that need a decision. Writes nothing.
  • import har applyCreate a new API from a HAR file. Every secret candidate needs a decision: from the flags, or prompted in a terminal. Fails if the API already exists.
  • import postman planPreview what a Postman import would create: resources, operations, requests, environments, middlewares, workflows, what cannot be converted, and the secret candidates that need a decision. Writes nothing.
  • import postman applyCreate a new API from a Postman collection. Every secret candidate needs a decision: from the flags, or prompted in a terminal. Scripts are written commented out under a throw, so they fail until rewritten. Fails if the API already exists.

craftr spec

Read the OpenAPI spec, or promote defined operations into it.

  • spec readPrint the effective OpenAPI spec, or the raw imported spec with --imported.
  • spec promoteWrite defined operations, with their parameters, request body and responses, into the API spec (spec.imported.json). The API then owns its spec: an upstream file or URL source is detached.

craftr req

List, run, and manage request instances.

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

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 listList every workflow in the project.
  • 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 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 move-blockMove a block, with its children and scripts, to another workflow. Clashing block ids get a numeric suffix; references that now cross workflows are listed in brokenReferences.
  • 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 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 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 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.