> For the complete documentation index, see [llms.txt](https://docs.stacksync.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stacksync.com/developers/getting-started-with-stacksync-cli/cli-command-reference.md).

# CLI Command Reference

Reference for all Stacksync CLI commands.

Run the following to view available options for any command:

```bash
stacksync <command> --help
```

### Setup

| Command                               | Description                                         |
| ------------------------------------- | --------------------------------------------------- |
| `stacksync`                           | Show the welcome screen and getting-started steps.  |
| `stacksync --help`                    | List all available commands.                        |
| `stacksync login`                     | Authenticate the CLI with your Stacksync workspace. |
| `stacksync update`                    | Update the CLI to the latest available version.     |
| `stacksync env`                       | View or update CLI configuration.                   |
| `stacksync --version`, `stacksync -V` | Display the installed CLI version.                  |

### Login

```bash
stacksync login
```

By default, the command prompts you to authenticate through the web or provide an API key.

#### Options

| Option             | Description                                                                                          |
| ------------------ | ---------------------------------------------------------------------------------------------------- |
| `--api-key <key>`  | Authenticate with an API key without using the interactive prompts.                                  |
| `--workspace <id>` | Set the default workspace. Use with `--api-key` for non-interactive authentication.                  |
| `--check`          | Print the current login status and exit. Returns exit code `0` when authenticated and `1` otherwise. |

#### Non-interactive authentication

Use API key authentication for CI environments, scripts, remote systems, and agents:

```bash
stacksync login --api-key <key> --workspace <id>
```

### Update

```bash
stacksync update
```

#### Options

| Option    | Description                                                           |
| --------- | --------------------------------------------------------------------- |
| `--force` | Reinstall the CLI even when the installed version is already current. |

### Environment Configuration

Use `stacksync env` to view or modify CLI configuration.

| Command                       | Description                             |
| ----------------------------- | --------------------------------------- |
| `stacksync env`               | List all configuration values.          |
| `stacksync env <key>`         | Display a specific configuration value. |
| `stacksync env <key> <value>` | Set a configuration value.              |

### Workflow Connectors

| Command                                          | Description                                                                      |
| ------------------------------------------------ | -------------------------------------------------------------------------------- |
| `stacksync workflow-connector create "<name>"`   | Create a Workflow Connector project in the current directory.                    |
| `stacksync workflow-connector run`               | Run the current connector locally and connect it to your workspace for testing.  |
| `stacksync workflow-connector deploy`            | Deploy the current connector to your Stacksync workspace.                        |
| `stacksync workflow-connector delete`            | Delete the current connector.                                                    |
| `stacksync workflow-connector replay <selector>` | Replay a logged request against the local connector for debugging.               |
| `stacksync workflow-connector cdk [ref]`         | Display the tracked CDK version or switch to another version or release channel. |

### Run a Workflow Connector

```bash
stacksync workflow-connector run
```

#### Options

| Option            | Default | Description                                                                                            |
| ----------------- | ------: | ------------------------------------------------------------------------------------------------------ |
| `--port <n>`      |  `2323` | Set the local port. If the port is unavailable, the CLI automatically selects the next available port. |
| `--sync-build`    | Enabled | Continuously copy changed files into `.stacksync_build` for hot reload.                                |
| `--no-sync-build` |       — | Disable continuous build synchronization.                                                              |

### Replay a Request

Replay a previously logged request against a connector running locally:

```bash
stacksync workflow-connector replay <selector>
```

The selector can be:

| Selector     | Description                                                      |
| ------------ | ---------------------------------------------------------------- |
| `<trace-id>` | Replay the request matching the specified UUID trace ID.         |
| `first`      | Replay the first logged request.                                 |
| `last`       | Replay the most recent logged request.                           |
| `first+n`    | Replay the request `n` positions after the first request.        |
| `last-n`     | Replay the request `n` positions before the most recent request. |

#### Options

| Option       | Default | Description                                |
| ------------ | ------: | ------------------------------------------ |
| `--port <n>` |  `2323` | Local port where the connector is running. |

### Manage the CDK Version

Display or change the CDK version tracked by the current connector.

```bash
stacksync workflow-connector cdk
```

Examples:

```bash
stacksync workflow-connector cdk
stacksync workflow-connector cdk v2
stacksync workflow-connector cdk v1.0.0
stacksync workflow-connector cdk prod
```

| Reference    | Description                                         |
| ------------ | --------------------------------------------------- |
| No reference | Display the currently tracked CDK version.          |
| `v2`         | Track the latest release in the `v2` major version. |
| `v1.0.0`     | Pin the connector to an exact CDK release.          |
| `prod`       | Track the latest production build.                  |

### Workflow Modules

| Command                                     | Description                                                                                                            |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `stacksync workflow-module create "<name>"` | Add a module to the current Workflow Connector.                                                                        |
| `stacksync workflow-module delete "<name>"` | Remove a module from the current Workflow Connector. Run this command from the connector root or the module directory. |