Installation

API Craft ships as two pieces. They are independent; install one or both.

  • The desktop app (api-craft): the graphical IDE.
  • The CLI (craftr): the command-line interface, distributed on npm.

Both run the same core against the same project files, so they interoperate freely.

Desktop app

Coming soonPublic builds

Desktop builds aren't publicly downloadable yet; the download page will carry them as soon as they are. If you'd like a build before then, ask on the support repo.

When they land, the download page serves an installer per platform:

  • macOS: .dmg
  • Linux: .AppImage

The installer is around 40 MB.

Coming soonWindows app

A native Windows build isn't available yet. In the meantime the CLI runs on Windows (it's a normal npm package); see below.

Every build lives on the download page. The app is fully local: it does not require an account or a network connection to use.

Updates

The desktop app updates itself. It checks on launch, and Settings → Updates has a Check for updates now button for when you don't want to wait.

The same tab picks the update channel:

  • Stable: tested releases only. The default.
  • Beta: early builds, and every stable release. Beta is a superset of stable, not a parallel track: you never miss a stable version by being on it.
The Updates tab in Settings: current version, the Stable/Beta channel switch, and the check-now button

Switching takes effect at the next check. The choice is stored with the app's own settings, not in any project, so it follows the machine rather than the repository.

The CLI has the same two channels through npm's dist-tags:

npm install -g @apicrafthq/cli          # stable
npm install -g @apicrafthq/cli@beta     # beta

CLI

Install the CLI from npm, globally:

npm install -g @apicrafthq/cli

Or run it without installing:

npx @apicrafthq/cli --version

No Node on the machine? The download page will also serve standalone craftr binaries for Linux and macOS (x64 and arm64); drop one on your PATH and it runs on its own.

Verify the install:

craftr --version

The CLI binary is craftr. (api-craft is the desktop app.) Throughout these docs, every command-line example uses craftr.

Tab completion

craftr ships shell completion for bash, zsh and fish. Install it once:

craftr completion install

It picks the shell from $SHELL; pass --shell to choose another. Open a new shell afterwards, or re-source your rc file, and completion is live.

What it completes is read from the project you are standing in, not from a static list, so it knows your own API slugs, environment names, resource slugs, request references, workflow names, and the operation ids waiting to be mapped:

craftr req run Pet/<TAB>          # request instances under the Pet resource
craftr env read <TAB>             # dev, staging, prod, prod-eu, prod-eu-client-a
craftr workflow run <TAB>         # workflow names
craftr workflow run pets --env <TAB>   # <api>=<env> bindings the batch needs

Where it lands:

ShellScriptSourced from
bash~/.config/craftr/completion.basha marked block appended to ~/.bashrc
zsh~/.config/craftr/completion.zsha marked block appended to ~/.zshrc
fish~/.config/fish/completions/craftr.fishnothing, fish autoloads it

The rc block is delimited by # ###-begin-craftr-completion-### markers, so re-running the install replaces it rather than stacking copies. To remove both the script and the block:

craftr completion uninstall

Next

Head to the quick start to create a project, import a spec, and run your first request.