# execute-package

Learn how to run a package command.

This action runs a package command using the project's package manager, such as npx for npm, pnpx for pnpm, or the equivalent for other managers.

## Example

The following template scaffolds a new project using a package command:

**template.json5**

```json5
{
  "$schema": "https://schema.croct.com/json/v1/template.json",
  "title": "Project scaffold",
  "description": "Creates a new project using giget.",
  "options": {
    "name": {
      "type": "string",
      "description": "The project name.",
      "default": "my-project"
    }
  },
  "actions": [
    {
      "name": "execute-package",
      "command": "giget@latest",
      "arguments": [
        "gh:user/starter",
        "${options.name}"
      ]
    }
  ]
}
```

You can pass the project name using the `--name` flag:

```sh
croct use template.json5 --name my-app
```

### Interactive commands

Some commands display interactive prompts that require user input. Use [`interactions`](#interactions-prop) to automate responses so the template can run without manual intervention:

**template.json5**

```json5
{
  "$schema": "https://schema.croct.com/json/v1/template.json",
  "title": "Add components",
  "description": "Adds UI components using shadcn.",
  "actions": [
    {
      "name": "execute-package",
      "command": "shadcn@latest",
      "arguments": [
        "add",
        "button",
        "card"
      ],
      "interactions": [
        {
          "when": "Would you like to overwrite?",
          "then": ["y"],
          "always": true
        },
        {
          "when": "(Created|Skipped) \\d+ files?",
          "pattern": true,
          "final": true
        }
      ]
    }
  ]
}
```

The first rule answers "y" every time the overwrite prompt appears. The second rule uses a regular expression to detect when the command finishes and signals the end of interaction.

### Project scripts

Set [`script`](#script-prop) to true to run a project script instead of a package binary:

**template.json5**

```json5
{
  "$schema": "https://schema.croct.com/json/v1/template.json",
  "title": "Seed database",
  "description": "Runs the database seed script.",
  "actions": [
    {
      "name": "install"
    },
    {
      "name": "execute-package",
      "command": "seed",
      "script": true,
      "arguments": ["--force"]
    }
  ]
}
```

## Properties

These are the supported properties:

- `name`: `string`

  The action identifier. Always `execute-package` for this action.

- `command`: `string`

  The package or script name to run.

  For packages, this supports version specifiers like `giget@latest`. For scripts, this is the name defined in the project's `package.json`.

- `arguments`: `Array<string>` (optional)

  The arguments to pass to the command.

- `script`: `boolean` (optional) (default: false)

  Whether to treat the command as a project script.

- `runner`: `string` (optional)

  The package manager to use for running the command.

  Defaults to the package manager detected from the project. Supported values are `npm`, `yarn`, `pnpm`, and `bun`.

- `interactions`: `Array<object> | boolean` (optional)

  Automated responses to interactive prompts.

  Set to `true` to pass through all I/O directly to the terminal, or provide a list of interaction rules.

  Rules are evaluated in order against the command output. At least one rule must have `final` set to true.

  - `when`: `string`

    The text to match against the command output.

    When `pattern` is true, this is interpreted as a regular expression.

  - `then`: `Array<string>` (optional)

    The responses to send when the prompt matches.

    Each value is sent as literal text, except for the following special keystrokes:

    | Keystroke     | Description |
    | ------------- | ----------- |
    | `[enter]`     | Enter       |
    | `[space]`     | Space       |
    | `[up]`        | Arrow up    |
    | `[down]`      | Arrow down  |
    | `[left]`      | Arrow left  |
    | `[right]`     | Arrow right |
    | `[backspace]` | Backspace   |

    Either `then` or `final` must be specified.

  - `pattern`: `boolean` (optional) (default: false)

    Whether `when` is a regular expression.

  - `always`: `boolean` (optional) (default: false)

    Whether to respond every time the prompt appears.

    By default, each rule matches only once. Cannot be combined with `final`.

  - `final`: `boolean` (optional) (default: false)

    Whether to stop accepting input after this match.

    At least one rule in the list must be final. Either `then` or `final` must be specified.

- `output`: `string` (optional)

  The variable name to store the command output.

  Cannot be used when `interactions` is `true`.

## Explore

- [Install](/reference/cli/templates/actions/install): Learn how to install dependencies first.
- [Run](/reference/cli/templates/actions/run): Learn how to run a group of actions.
- [Change directory](/reference/cli/templates/actions/change-directory): Learn how to change directory before executing.
- [Add dependency](/reference/cli/templates/actions/add-dependency): Learn how to add a required package.