Frequently asked questions

The Guide explains concepts and end-to-end workflows.

The CLI section documents each command on its own page.

The API Reference documents the helpers and primitives used to build custom tasks and recipes.

By default, Catapult looks in the current directory for:

• deploy.ts
• deploy.config.ts
• deploy.js
• deploy.config.js

Run `deploy:setup` before the first deployment on a server.

It creates the remote directory structure Catapult expects and runs setup hooks registered by recipes.

Use `deploy` for the full deployment pipeline.

Use `rollback` to switch back to an earlier release.

Use `task` to run one registered task on the current release without launching a full deployment.

Catapult runs the task against the current published release on the target host.

If no deployment has happened yet, there is no current release to execute the task against.

Use `--host` when more than one host is configured and you want to skip the interactive selection prompt.

npx cata deploy -H production

For host-aware commands, Catapult prompts you to select one or more hosts when `--host` is not provided.

The `ssh` command prompts for a single host because it opens one interactive session.

Use `--branch` or `-b` on `deploy`.

That overrides the branch from the config only for the current command.

npx cata deploy --branch feature/my-feature

Pass `--config` or `-c`.

This is useful when you keep separate configs for staging, production, or multiple projects.

npx cata deploy -c deploy.staging.ts

If a lock remains after an interrupted deployment, run the unlock task when it is available.

You can list available tasks first if you want to confirm the task name.

npx cata task deploy:unlock -H production

npx cata list:tasks

`status` shows the current state of the selected host, including:

• the active release
• the healthcheck result when configured
• the Node.js and package-manager versions
• the latest revision metadata
• the deployment lock status