> ## 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.

# StackOne CLI

> 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

Set up the agent, and the MCP server that gives an AI coding assistant StackOne's tools.

| Command                         | Description                                                                                                                  |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `stackone agent setup --local`  | Authenticate, write `.mcp.json`, and install the connector-building skills into `.claude/` plus a guide block in `CLAUDE.md` |
| `stackone agent setup --global` | Authenticate and register the MCP server in `~/.claude.json`. No skills or guide                                             |
| `stackone agent chat`           | Interactive session with the agent                                                                                           |
| `stackone agent run "<prompt>"` | Run the agent once, non-interactively                                                                                        |
| `stackone agent skills`         | List the bundled skills                                                                                                      |
| `stackone agent sync`           | Refresh this project's skills and guide                                                                                      |
| `stackone agent cleanup`        | Remove stored credentials and configuration                                                                                  |

```bash theme={null}
# In a connector repo: auth + MCP server + skills + CLAUDE.md guide
stackone agent setup --local

# Install into a directory other than the current one
stackone agent setup --local --path ~/code/custom-connectors

# Auth + MCP server only, for projects that aren't connector repos
stackone agent setup --global

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

The API key is stored in `~/.stackone/agent-config.json` either way. The MCP server entry goes to `~/.claude.json` for `--global`, or the project's `.mcp.json` for `--local`.

<Tip>
  Use `--local` in the repo where you build connectors, since it's the only mode that installs the skills and the guide. It authenticates you at the same time, so `--global` is not a prerequisite. Passing neither flag prompts for the mode.
</Tip>

#### Chat and one-shot runs

Most of the time you'll build in [Claude Code](https://claude.com/claude-code), which picks up the `.mcp.json` and skills that `agent setup --local` installs. `agent chat` is the alternative when you'd rather stay in the terminal without a separate editor or assistant. It defaults to `build` mode, accepts `/commands`, and you can point it at what you're working on:

```bash theme={null}
stackone agent chat --connector my_provider

# Switch mode with --mode (build, test, or research)
stackone agent chat --mode test --connector my_provider --action list_employees \
  --goal "check pagination returns every page"
```

`--temperature` (0 to 1, default 0.5) adjusts how much the agent varies its approach.

For scripted use, `agent run` takes the prompt as an argument and exits when it's done:

```bash theme={null}
stackone agent run "add pagination to list_employees" --mode build --max-turns 40
```

`--max-turns` defaults to 25.

#### Skills

`agent setup --local` installs a set of connector-building skills into `.claude/skills/`. List what you have, and the subset recommended for a mode:

```bash theme={null}
stackone agent skills
stackone agent skills --mode build
```

After upgrading the CLI, refresh the copies in your project:

```bash theme={null}
stackone agent sync

# Report drift and exit non-zero instead of writing, for CI
stackone agent sync --check
```

***

### 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}
  {
    "path": { "id": "emp_123" },
    "queryParams": { "include": "manager" }
  }
  ```
</CodeGroup>

**Params structure:** each top-level key corresponds to an input's `in:` location in the action's YAML. Put every value under the key that matches where the input is sent.

| Key           | Inputs it carries                 |
| ------------- | --------------------------------- |
| `path`        | `in: path` — URL path parameters  |
| `queryParams` | `in: query`                       |
| `header`      | `in: headers` (singular `header`) |
| `body`        | `in: body`                        |

You can pass the same object inline instead of a file:

```bash theme={null}
stackone run \
  --connector connectors/[provider]/[provider].connector.s1.yaml \
  --account-id [account-id] \
  --action-id get_employee \
  --params '{"path": {"id": "emp_123"}, "queryParams": {"include": "manager"}}'
```

<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](/embed/api-keys) 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 (saves to ./connectors/my_provider/ by default)
stackone pull --connector my_provider --profile prod

# Pull a specific version to a different directory
stackone pull --connector my_provider@1.0.0 --profile prod --output-path ./custom-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="First Connector" icon="rocket" href="/connector-building/first-connector">
    Build a connector from scratch with these commands
  </Card>

  <Card title="GitHub CI/CD" icon="github" href="/connector-building/github-ci-cd">
    Automated validation and publishing with GitHub Actions
  </Card>
</CardGroup>