> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> StackOne CLI commands for building, validating, testing, and deploying connectors

The StackOne CLI (`@stackone/cli`) provides commands for building, validating, testing, and deploying custom connectors.

<Card title="Full Documentation" icon="npm" href="https://www.npmjs.com/package/@stackone/cli">
  Complete CLI documentation on npm
</Card>

## Installation

```bash theme={null}
npm install -g @stackone/cli
```

***

## Command Reference

### Agent Commands

Configure the StackOne MCP server for AI coding assistants like Claude, Cursor, and Windsurf.

| Command                         | Description                                   |
| ------------------------------- | --------------------------------------------- |
| `stackone agent setup --global` | Configure MCP tools globally in `~/.stackone` |
| `stackone agent setup --local`  | Configure MCP tools for current project only  |
| `stackone agent cleanup`        | Remove stored credentials and configuration   |

```bash theme={null}
# Global setup - configures MCP server for all projects (recommended)
stackone agent setup --global

# Project-scoped setup - configures MCP server for current directory
stackone agent setup --local

# Remove all API keys and credentials
stackone agent cleanup
```

<Tip>
  Use `--global` setup when you want the StackOne MCP tools available across all your projects. Use `--local` for project-specific configurations.
</Tip>

***

### Connector Development

| Command                    | Description                                    |
| -------------------------- | ---------------------------------------------- |
| `stackone validate <path>` | Validate connector YAML syntax and structure   |
| `stackone run`             | Execute a connector action locally for testing |

```bash theme={null}
# Validate with watch mode
stackone validate ./my-connector/ --watch

# Run an action with local credentials
stackone run \
  --connector my-connector.connector.s1.yaml \
  --account account.json \
  --credentials credentials.json \
  --action-id list_employees \
  --debug

# Run with parameters
stackone run \
  --connector my-connector.connector.s1.yaml \
  --account account.json \
  --credentials credentials.json \
  --action-id get_employee \
  --params params.json

# Run custom action code (for testing action definitions)
stackone run \
  --connector my-connector.connector.s1.yaml \
  --account-id acme-corp-provider \
  --action ./custom-action.yaml

# Save output to file
stackone run \
  --connector my-connector.connector.s1.yaml \
  --account-id acme-corp-provider \
  --action-id list_employees \
  --output-file results.json
```

**Test file formats:**

<CodeGroup>
  ```json account.json theme={null}
  {
    "environment": "production",
    "provider": "provider"
  }
  ```

  ```json credentials.json (API Key) theme={null}
  {
    "apiKey": "your_api_key"
  }
  ```

  ```json credentials.json (OAuth2) theme={null}
  {
    "accessToken": "token",
    "refreshToken": "refresh_token",
    "clientId": "client_id",
    "clientSecret": "client_secret"
  }
  ```

  ```json params.json theme={null}
  {
    "employee_id": "12345"
  }
  ```
</CodeGroup>

<Tip>
  **Faster iteration:** Once your connector is pushed or an account is already linked, skip the credentials file and use `--account-id` instead:

  ```bash theme={null}
  stackone run \
    --connector my-connector.connector.s1.yaml \
    --account-id acme-corp-provider \
    --action-id list_employees
  ```

  This uses stored credentials from the linked account, making it easier to iterate on action logic without managing local credential files.

  **Note:** Using `--account-id` requires an API key with `connectors:read` scope.
</Tip>

### Deployment

<Note>
  Deployment commands require an API key with **Connectors** scopes. See [API Keys](/guides/api-keys#configure-api-key-scopes-optional) to generate one.
</Note>

| Command                            | Description                                            | Required Scope     |
| ---------------------------------- | ------------------------------------------------------ | ------------------ |
| `stackone push <path>`             | Upload connector to StackOne registry                  | `connectors:write` |
| `stackone pull`                    | Download connector files to local filesystem           | `connectors:read`  |
| `stackone drop <provider@version>` | Delete a connector version from registry               | `connectors:write` |
| `stackone get`                     | Retrieve connector configuration (YAML or JSON output) | `connectors:read`  |

```bash theme={null}
# Push using saved profile
stackone push ./my-connector/ --profile prod

# Push with API key directly
stackone push ./my-connector/ --api-key v1.eu1.xxxxx

# Pull connector files to local directory
stackone pull --connector my_provider --output ./connectors/

# Pull specific version
stackone pull --connector my_provider@1.0.0 --output ./connectors/

# Get connector config as YAML (default)
stackone get --connector my_provider

# Get connector config from a linked account
stackone get --account-id acme-corp-provider --format json --output-file config.json
```

***

### Configuration

| Command            | Description                                     |
| ------------------ | ----------------------------------------------- |
| `stackone init`    | Configure authentication profiles interactively |
| `stackone version` | Show version with update check                  |
| `stackone update`  | Update CLI to latest version                    |

```bash theme={null}
# Interactive setup (prompts for profile name and API key)
stackone init

# Setup for different environments
stackone init --env staging
stackone init --env production

# Check version and available updates
stackone version

# Update to latest version
stackone update
```

***

## Environment Variables

| Variable                   | Description                                    |
| -------------------------- | ---------------------------------------------- |
| `STACKONE_AGENT_MCP_TOKEN` | MCP server access token (set by `agent setup`) |

<Note>
  API keys are passed via `--api-key` flag or stored in your profile configuration, not as environment variables.
</Note>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Build Connectors" icon="rocket" href="/guides/connector-engine/introduction">
    Get started building connectors
  </Card>

  <Card title="CI/CD Setup" icon="github" href="/guides/connector-engine/github-workflow">
    Automated deployment with GitHub Actions
  </Card>
</CardGroup>