StackOne CLI

A command-line interface for StackOne Connect operations.

Installation

Install globally via npm:

npm install -g @stackone/cli

Usage

After installation, you can use the stackone command from anywhere:

stackone --help
stackone -h

Commands

init

Initialize and configure the StackOne CLI by creating configuration profiles. This command allows you to store multiple configuration profiles for easy access.

stackone init

Options:

• -e, --env <environment> - Specify the environment for the configuration profile (production, staging or custom value). Defaults to production if not provided. When using a custom environment, you will be prompted to enter the API URL.

The command will interactively prompt you for:

1. Profile label - A unique name for this configuration profile
2. API Url - Only when the environment is specified and is not production or staging
3. API Key - Your StackOne API key

Features:

• Multiple configurations: Store different configs for various environments
• Overwrite protection: Prompts for confirmation before overwriting existing configs
• Persistent storage: Configurations are saved in ~/.stackone
• Reusable: Run the command multiple times to create different configurations

push

Push connector(s) file(s) to the StackOne API registry. This command can use either a configuration profile created with the init command or provide credentials directly via command-line options.

stackone push --profile <profile-label> path/to/connector.s1.yaml

or

stackone push --profile <profile-label> path/to/connectors/

or using direct credentials:

stackone push --api-key <your-api-key> path/to/connector.s1.yaml

or with custom API URL:

stackone push --api-key <your-api-key> --api-url <api-url> path/to/connector.s1.yaml

Arguments:

• <path> - Path to the connector file or folder with connectors to upload

Options:

• -p, --profile <label> - Configuration profile to use
• --api-key <api-key> - API key to use for authentication (alternative to using a profile)
• --api-url <api-url> - API URL to use (defaults to https://api.stackone.com if not specified)

Note: You must provide either --profile or --api-key. If using --api-key, the --api-url option is optional and will default to the production API URL.

Features:

• Flexible authentication: Use either a saved profile or provide credentials directly
• Profile validation: Ensures the specified profile exists before uploading (when using --profile)
• File validation: Checks that the file exists and is a valid connector before attempting upload
• Batch upload: Supports uploading multiple connectors from a directory

pull

Pull a connector from the StackOne API registry to your local filesystem. This command fetches a connector from the registry and saves it locally, with interactive conflict resolution when the connector already exists.

stackone pull --connector [email protected] --profile <profile-label>

or using direct credentials:

stackone pull --connector [email protected] --api-key <your-api-key>

or with custom API URL:

stackone pull --connector [email protected] --api-key <your-api-key> --api-url <api-url>

or pulling the latest version:

stackone pull --connector my-provider --profile <profile-label>

Options:

• --connector <connector> - Connector identifier in format provider_key@version (e.g., [email protected]), provider_key to pull the latest version, or with version wildcards (e.g., [email protected], [email protected] or my-provider@latest)
• -o, --output-path <output-path> - Directory path to save the connector to (defaults to ./connectors/<provider_key>/)
• -p, --profile <label> - Configuration profile to use
• --api-key <api-key> - API key to use for authentication (alternative to using a profile)
• --api-url <api-url> - API URL to use (defaults to https://api.stackone.com if not specified)

Note: You must provide either --profile or --api-key. If using --api-key, the --api-url option is optional and will default to the production API URL.

Usage Examples:

1. Pull specific version with profile:

   stackone pull --connector [email protected] --profile production

2. Pull latest version with API key:

   stackone pull --connector my-provider --api-key your-api-key

3. Pull to custom directory:

   stackone pull --connector [email protected] --profile production --output-path ./my-connectors

4. Pull with custom API URL:

   stackone pull --connector [email protected] --api-key your-api-key --api-url https://staging.api.stackone.com

Conflict Resolution:

When pulling a connector that already exists locally, the command will:

1. Display a diff showing the differences between local and registry versions
2. Prompt you to choose how to resolve the conflict:
   • Override with registry version - Replace local file with the registry version
   • Keep local version - Discard changes and keep the local file
   • Interactive resolution - Manually resolve conflicts line by line

Features:

• Flexible authentication: Use either a saved profile or provide credentials directly
• Version flexibility: Pull specific versions, use wildcards (e.g., 1.x.x, 2.1.x, latest), or omit version for latest
• Interactive conflict resolution: Smart diff-based conflict resolution when local changes exist
• Profile validation: Ensures the specified profile exists before fetching (when using --profile)
• Automatic file organization: Saves connectors in organized directory structure (./connectors/<provider_key>/)
• Local validation: Validates local connector before conflict resolution
• Clear feedback: Informative success and error messages with color-coded output

drop

Drop (delete) a specific connector version from the StackOne API registry. This command can use either a configuration profile created with the init command or provide credentials directly via command-line options.

stackone drop <connector> --profile <profile-label>

or using direct credentials:

stackone drop <connector> --api-key <your-api-key>

or with custom API URL:

stackone drop <connector> --api-key <your-api-key> --api-url <api-url>

Arguments:

• <connector> - The connector identifier in the format provider_key@version (e.g., [email protected])

Options:

• -p, --profile <label> - Configuration profile to use
• --api-key <api-key> - API key to use for authentication (alternative to using a profile)
• --api-url <api-url> - API URL to use (defaults to https://api.stackone.com if not specified)

Note: You must provide either --profile or --api-key. If using --api-key, the --api-url option is optional and will default to the production API URL.

Features:

• Flexible authentication: Use either a saved profile or provide credentials directly
• Profile validation: Ensures the specified profile exists before attempting deletion (when using --profile)
• Precise targeting: Delete specific connector versions without affecting other versions
• Clear feedback: Informative success and error messages with color-coded output

get

Get (download) a connector from the StackOne registry. This command can use either a configuration profile created with the init command or provide credentials directly via command-line options.

stackone get --connector [email protected] --profile <profile-label>

or get the latest version:

stackone get --connector my-provider --profile <profile-label>

or using direct credentials:

stackone get --connector [email protected] --api-key <your-api-key>

or fetch from an account:

stackone get --account-id acc_123 --profile <profile-label>

Options:

• --connector <connector> - Connector identifier in format provider_key@version (e.g., [email protected]), provider_key to get the latest version, or with version wildcards (e.g., [email protected], [email protected] or my-provider@latest)
• --account-id <account-id> - Account ID to fetch the connector from
• -f, --format <format> - Output format: yaml or json (default: yaml)
• -o, --output-file <output-file> - File path to write the connector to (if not specified, outputs to stdout)
• -p, --profile <label> - Configuration profile to use
• --api-key <api-key> - API key to use for authentication (alternative to using a profile)
• --api-url <api-url> - API URL to use (defaults to https://api.stackone.com if not specified)

Note:

• You must provide either --profile or --api-key. If using --api-key, the --api-url option is optional and will default to the production API URL.
• You must provide either --connector or --account-id, but not both.

Usage Examples:

1. Get connector from registry with profile:

   stackone get --connector [email protected] --profile production

2. Get latest version from registry with API key:

   stackone get --connector my-provider --api-key your-api-key

3. Get connector from account:

   stackone get --account-id acc_123 --profile production

4. Get connector in JSON format:

   stackone get --connector [email protected] --profile production --format json

5. Get connector and save to file:

   stackone get --connector [email protected] --profile production --output-file my-connector.s1.yaml

6. Get connector with custom API URL:

   stackone get --connector [email protected] --api-key your-api-key --api-url https://staging.api.stackone.com

Features:

• Flexible authentication: Use either a saved profile or provide credentials directly
• Version flexibility: Get specific versions, use wildcards (e.g., 1.x.x, 2.1.x, latest), or omit version for latest
• Multiple sources: Fetch connectors from registry by identifier or from specific accounts
• Format conversion: Output in YAML (default) or JSON format
• File output: Save to file or output to stdout for piping
• Profile validation: Ensures the specified profile exists before fetching (when using --profile)
• Clear feedback: Informative success and error messages with color-coded output

validate

Validate a StackOne connector file:

stackone validate path/to/connector.s1.yaml

Validate multiple connector files at once in a directory (recursive):

stackone validate path/to/connectors/

Options:

• -w or --watch: Watch for changes in the specified directory of file and validate connectors as they change.

Note: The file extension of a connector file needs to be .s1.yaml. The file extension can be omitted.

run

Execute a connector action locally with full control over connector configuration, account details, and execution parameters. This command is ideal for testing and debugging connectors during development.

stackone run --connector path/to/connector.s1.yaml --account-id <account-id> --profile <profile-label>

or using direct credentials:

stackone run --account-id <account-id> --api-key <your-api-key>

Options:

• --connector <connector> - Path to the connector file to run, inline connector YAML string, or connector identifier in format provider_key@version, provider_key for latest, or with version wildcards (e.g., [email protected], [email protected] or my-provider@latest) to fetch from registry (optional when using --account-id, the connector will be fetched from account API)
• --action <action> - Path to an action file or inline action YAML code to add to the connector
• --action-id <action-id> - Specific action ID to execute. If not provided, the last action in the connector will be executed
• --account <account> - Path to a JSON file with account details or inline JSON string (see Account Format below)
• --account-id <account-id> - Account ID to fetch from StackOne API (requires either --profile or --api-key). When provided without --connector, the connector will also be fetched from the API
• --params <params> - Path to a JSON file with action parameters or inline JSON string (see Parameters Format below)
• --credentials <credentials> - Path to a JSON file with credentials or inline JSON string (see Credentials Format below)
• -p, --profile <label> - Configuration profile to use
• --api-key <api-key> - API key to use for authentication (alternative to using a profile)
• --api-url <api-url> - API URL to use (defaults to https://api.stackone.com if not specified)
• -o, --output-file <output-file> - File path to write the execution output to (JSON format)
• -d, --debug - Enable debug mode to include execution steps and detailed information in the output

Note: You must provide either --profile or --api-key when using --account-id. If using --api-key, the --api-url option is optional and will default to the production API URL.

Usage Examples:

1. Run with account from API using profile (connector fetched automatically):

   stackone run --account-id acc_123 --profile production

2. Run with account from API using API key (connector fetched automatically):

   stackone run --account-id acc_123 --api-key your-api-key

3. Run with custom API URL:

   stackone run --account-id acc_123 --api-key your-api-key --api-url https://staging.api.stackone.com

4. Run with connector identifier from registry:

   stackone run --connector [email protected] --account account.json --api-key your-api-key

5. Run with connector from registry and account from API:

   stackone run --connector [email protected] --account-id acc_123 --profile production

6. Run with account from API and specific connector file:

   stackone run --connector connector.s1.yaml --account-id acc_123 --profile production

7. Run with local account file & credentials:

   stackone run --connector connector.s1.yaml --account account.json --credentials credentials.json

8. Run with inline account data:

   stackone run --connector connector.s1.yaml --account '{"auth_config_key":"basic","credentials":{"username":"user","password":"pass"}}'

9. Run specific action with parameters using API key (connector auto-fetched):

   stackone run --action-id list_employees --account-id acc_123 --api-key your-api-key --params params.json

10. Run with custom action file:

    stackone run --connector connector.s1.yaml --action custom-action.yaml --account account.json

11. Run with debug mode and output to file (connector auto-fetched):

    stackone run --account-id acc_123 --profile production --debug --output-file result.json

Account Format (JSON):

When using --account with a file or inline JSON, use this structure:

{
  "auth_config_key": "basic",
  "environment": "production",
  "organization_id": "org_123",
  "account_id": "acc_456",
  "project_id": "proj_789"
}

All fields are optional except for auth_config_key.

Credentials Format (JSON):

When using --credentials, provide a key-value object:

{
  "api_key": "your_api_key",
  "username": "your_username",
  "password": "your_password"
}

Note: Credentials provided via --credentials will merge with and override credentials from --account or --account-id.

Parameters Format (JSON):

When using --params, provide parameters for path, query, headers, and body:

{
  "path": {
    "id": "employee_123"
  },
  "queryParams": {
    "page": "1",
    "page_size": "10"
  },
  "header": {
    "X-Custom-Header": "value"
  },
  "body": {
    "name": "John Doe",
    "email": "[email protected]"
  }
}

All fields are optional and default to empty objects {}.

Requirements:

• Either --account or --account-id must be provided
• When using --account-id, either --profile or --api-key is required
• When using connector identifier format (provider_key@version or provider_key), either --profile or --api-key is required
• You must provide either --profile or --api-key, not both
• When using --action, the --connector option is required
• A connector can be provided via:
  • --connector with a file path or inline YAML
  • --connector with identifier format (provider_key@version) to fetch from registry
  • Automatically fetched from account API when using --account-id without --connector

Features:

• Flexible connector loading: Load from file path, provide inline YAML, fetch from registry using provider_key@version, provider_key for latest, or version wildcards (e.g., 1.x.x or latest), or auto-fetch from API using account ID
• Flexible authentication: Use either a saved profile or provide credentials directly via command-line options
• Dynamic action injection: Add custom actions to existing connectors on-the-fly
• Multiple authentication methods: Use API-fetched accounts or local account data
• Credential override: Merge or override credentials at runtime
• Comprehensive parameters: Support for path params, query params, headers, and body
• Debug mode: Get detailed execution information including step-by-step processing
• Output redirection: Save results to file for further processing or analysis
• Error handling: Clear error messages with execution details when actions fail

version

Show CLI version information. If a new version is available, it will prompt you to update:

stackone version

--version

Show the current version of the CLI:

stackone --version
stackone -v

update

Update the StackOne CLI to the latest version. This command checks for newer versions and automatically updates the CLI if a newer version is available.

stackone update

Options:

• -f, --force - Force reinstall the CLI even if already on the latest version

Usage Examples:

1. Check and update to latest version:

   stackone update

2. Force reinstall (useful for fixing corrupted installations):

   stackone update --force

Features:

• Automatic version detection: Checks NPM registry for the latest available version
• Smart updates: Only updates when a newer version is available (unless --force is used)
• Clear feedback: Shows current and new version numbers with color-coded output

How it works:

The update command compares your currently installed version with the latest version published on NPM. If a newer version is found, it will:

1. Display the version upgrade path (e.g., 1.0.0 → 1.1.0)
2. Automatically run the install command

If you're already on the latest version, the command will confirm this and exit without making changes (unless you use the --force flag).

AI Agent Commands

The CLI includes powerful AI agent commands for building and testing connectors. The agent uses Anthropic's Claude (via StackOne backend) with access to tools including file operations, web search, and StackOne's Falcon MCP server.

Quick Start

# Authenticate with StackOne
stackone agent setup

# Start interactive chat
stackone agent chat --mode build

agent chat

Start an interactive chat session with the agent:

stackone agent chat --mode build

Options:

• -m, --mode <mode> - Mode: build, test, or research (default: build)
• -c, --connector <name> - Connector name (optional)
• -a, --action <name> - Action name (optional)
• -g, --goal <goal> - Initial goal/message (optional)
• -v, --verbose - Enable verbose logging

Features:

• Beautiful Ink-based terminal UI
• Real-time typing animation
• Tool execution visualization
• Multi-turn conversations
• Exit with Esc or Ctrl+C

agent setup

Setup the StackOne agent. This command can be used for global authentication or local project configuration.

Global setup - Initialize and authenticate the StackOne agent globally:

stackone agent setup --global

The command will interactively prompt you for:

1. Email - Your StackOne account email
2. Password - Your StackOne account password

Configuration is saved to ~/.stackone/agent-config.json with secure permissions. API keys expire after 24 hours.

Local setup - Setup the StackOne agent for a specific project:

stackone agent setup --local

This command requires prior authentication with agent setup --global. It creates:

• CLAUDE.md - Agent workflow instructions and guidelines
• .mcp.json - Local MCP server configuration

The MCP configuration uses the STACKONE_AGENT_MCP_TOKEN environment variable, which is automatically managed by the agent setup command.

Options:

• -l, --local - Setup local project configuration (default)

agent cleanup

Remove all API keys and credentials from agent configurations. This command:

• Removes ~/.stackone/agent-config.json (global auth config)
• Removes MCP server from Claude configuration
• Cleans .mcp.json file (replaces Bearer tokens with environment variable references)

stackone agent cleanup

Safety: This command only modifies files created by agent setup commands. It does not scan or modify connector YAML files or other project files.

Local Development

# Install dependencies
npm install

# Build the package
npm run build

# Link for global testing
npm link

# Run tests
npm test

# Lint and format
npm run lint:fix

Building

npm run build

Testing

npm test

Publishing

The package is configured to be published to NPM with public access:

npm run publish-release

Architecture

Core CLI

• Commander.js - Command line parsing
• Chalk - Terminal colors and styling
• Inquirer - Interactive prompts
• Ora - Loading spinners
• TypeScript - Type safety
• Tsdown - Bundling
• Vitest - Testing

AI Agent System

The agent commands use @stackone/agent-harness - a composable agent runtime:

Framework:

• Anthropic SDK (direct integration, no extra abstraction layers)
• Claude Sonnet 4 - Latest model with extended context and tool use
• Skills System - Pluggable tool architecture with dynamic loading

Architecture:

┌─────────────────────────────────────────┐
│         @stackone/cli                   │
│                                         │
│  ┌───────────────────────────────────┐  │
│  │   Agent Commands                  │  │
│  │   • build  • test  • chat        │  │
│  └─────────────┬─────────────────────┘  │
│                │ imports                 │
│                ↓                         │
│  ┌───────────────────────────────────┐  │
│  │   @stackone/agent-harness        │  │
│  │   (separate composable library)  │  │
│  │                                   │  │
│  │   • AgentRuntimeV2               │  │
│  │   • SkillLoader                  │  │
│  │   • Built-in Skills (4)          │  │
│  │   • MCP Client                   │  │
│  └───────────────────────────────────┘  │
│                │                         │
│                ↓ connects to             │
│  ┌───────────────────────────────────┐  │
│  │   MCP Servers                    │  │
│  │   • StackOne Falcon (35 tools)  │  │
│  │   • Grep (1 tool)                │  │
│  └───────────────────────────────────┘  │
└─────────────────────────────────────────┘

Design Principles:

1. No abstraction layers - Direct Anthropic SDK for full control
2. Composable - Agent harness is a separate library
3. Skills over tools - Organized, discoverable, testable
4. MCP integration - Dynamic tool loading from MCP servers
5. Streaming support - Real-time token and tool call updates

Why Anthropic SDK directly?

• No Vercel AI SDK or LangChain - fewer dependencies, simpler debugging
• Direct access to all Anthropic features
• Smaller bundle size
• Full control over prompt engineering and tool calling