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

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

Chat and one-shot runs

Most of the time you’ll build in 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:

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:

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:

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

Chat and one-shot runs

Skills

Connector Development

Deployment

Configuration

Environment Variables

Next Steps

First Connector

GitHub CI/CD

Full Documentation

​Installation

​Command Reference

​Agent Commands

​Chat and one-shot runs

​Skills

​Connector Development

​Deployment

​Configuration

​Environment Variables

​Next Steps

First Connector

GitHub CI/CD

Installation

Command Reference

Agent Commands

Chat and one-shot runs

Skills

Connector Development

Deployment

Configuration

Environment Variables

Next Steps