StackOne CLI

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

Full Documentation

Complete CLI documentation on npm

Installation

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 skills`	List the bundled skills
`stackone agent sync`	Refresh this project’s skills and guide
`stackone agent cleanup`	Remove stored credentials and configuration

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

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.

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:

stackone agent skills
stackone agent skills --mode build

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

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

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

{
  "environment": "production",
  "provider": "provider"
}

{
  "apiKey": "your_api_key"
}

{
  "accessToken": "token",
  "refreshToken": "refresh_token",
  "clientId": "client_id",
  "clientSecret": "client_secret"
}

{
  "path": { "id": "emp_123" },
  "queryParams": { "include": "manager" }
}

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:

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"}}'

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

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.

Deployment

Deployment commands require an API key with Connectors scopes. See API Keys to generate one.

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`

# 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

# 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`)

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

Full Documentation

Installation

Command Reference

Agent Commands

Skills

Connector Development

Deployment

Configuration

Environment Variables

Next Steps

First Connector

GitHub CI/CD

Full Documentation

​Installation

​Command Reference

​Agent Commands

​Skills

​Connector Development

​Deployment

​Configuration

​Environment Variables

​Next Steps

First Connector

GitHub CI/CD

Installation

Command Reference

Agent Commands

Skills

Connector Development

Deployment

Configuration

Environment Variables

Next Steps