@stackone/cli
Advanced tools
A command-line interface for StackOne Connect operations.
Install globally via npm:
npm install -g @stackone/cli
After installation, you can use the stackone command from anywhere:
stackone --help
stackone -h
initInitialize 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:
Features:
~/.stackonepushPush 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 uploadOptions:
-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)--force - Force push the connector, bypassing version conflict checksNote: 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:
--profile)--force to bypass version conflict checks and overwrite an existing connector versionpullPull 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 my-provider@1.0.0 --profile <profile-label>
or using direct credentials:
stackone pull --connector my-provider@1.0.0 --api-key <your-api-key>
or with custom API URL:
stackone pull --connector my-provider@1.0.0 --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., my-provider@1.0.0), provider_key to pull the latest version, or with version wildcards (e.g., my-provider@1.x.x, my-provider@2.1.x 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)--builtin - Use the builtin (StackOne) version of the connector--custom - Use the custom (organization) version of the connector--owner <owner> - Explicitly specify the owner to disambiguate between multiple versions of the same connectorNote: 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:
Pull specific version with profile:
stackone pull --connector my-provider@1.0.0 --profile production
Pull latest version with API key:
stackone pull --connector my-provider --api-key your-api-key
Pull to custom directory:
stackone pull --connector my-provider@1.0.0 --profile production --output-path ./my-connectors
Pull with custom API URL:
stackone pull --connector my-provider@1.0.0 --api-key your-api-key --api-url https://staging.api.stackone.com
Pull builtin (StackOne) version:
stackone pull --connector my-provider@1.0.0 --profile production --builtin
Pull custom (organization) version:
stackone pull --connector my-provider@1.0.0 --profile production --custom
Pull with explicit owner:
stackone pull --connector my-provider@1.0.0 --profile production --owner my-org
Conflict Resolution:
When pulling a connector that already exists locally, the command will:
Features:
1.x.x, 2.1.x, latest), or omit version for latest--profile)./connectors/<provider_key>/)dropDrop (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., my-provider@1.0.0)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:
--profile)getGet (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 my-provider@1.0.0 --profile <profile-label>
or get the latest version:
stackone get --connector my-provider --profile <profile-label>
or using direct credentials:
stackone get --connector my-provider@1.0.0 --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., my-provider@1.0.0), provider_key to get the latest version, or with version wildcards (e.g., my-provider@1.x.x, my-provider@2.1.x 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)--builtin - Use the builtin (StackOne) version of the connector--custom - Use the custom (organization) version of the connector--owner <owner> - Explicitly specify the owner to disambiguate between multiple versions of the same connectorNote:
--profile or --api-key. If using --api-key, the --api-url option is optional and will default to the production API URL.--connector or --account-id, but not both.Usage Examples:
Get connector from registry with profile:
stackone get --connector my-provider@1.0.0 --profile production
Get latest version from registry with API key:
stackone get --connector my-provider --api-key your-api-key
Get connector from account:
stackone get --account-id acc_123 --profile production
Get connector in JSON format:
stackone get --connector my-provider@1.0.0 --profile production --format json
Get connector and save to file:
stackone get --connector my-provider@1.0.0 --profile production --output-file my-connector.s1.yaml
Get connector with custom API URL:
stackone get --connector my-provider@1.0.0 --api-key your-api-key --api-url https://staging.api.stackone.com
Get builtin (StackOne) version:
stackone get --connector my-provider@1.0.0 --profile production --builtin
Get custom (organization) version:
stackone get --connector my-provider@1.0.0 --profile production --custom
Get with explicit owner:
stackone get --connector my-provider@1.0.0 --profile production --owner my-org
Features:
1.x.x, 2.1.x, latest), or omit version for latest--profile)validateValidate 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.
runExecute 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., my-provider@1.x.x, my-provider@2.1.x 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--builtin - Use the builtin (StackOne) version of the connector when fetching from the registry--custom - Use the custom (organization) version of the connector when fetching from the registry--owner <owner> - Explicitly specify the owner to disambiguate between multiple versions of the same connector in the registryNote: 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:
Run with account from API using profile (connector fetched automatically):
stackone run --account-id acc_123 --profile production
Run with account from API using API key (connector fetched automatically):
stackone run --account-id acc_123 --api-key your-api-key
Run with custom API URL:
stackone run --account-id acc_123 --api-key your-api-key --api-url https://staging.api.stackone.com
Run with connector identifier from registry:
stackone run --connector my-provider@1.0.0 --account account.json --api-key your-api-key
Run with connector from registry and account from API:
stackone run --connector my-provider@1.0.0 --account-id acc_123 --profile production
Run with account from API and specific connector file:
stackone run --connector connector.s1.yaml --account-id acc_123 --profile production
Run with local account file & credentials:
stackone run --connector connector.s1.yaml --account account.json --credentials credentials.json
Run with inline account data:
stackone run --connector connector.s1.yaml --account '{"auth_config_key":"basic","credentials":{"username":"user","password":"pass"}}'
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
Run with custom action file:
stackone run --connector connector.s1.yaml --action custom-action.yaml --account account.json
Run with debug mode and output to file (connector auto-fetched):
stackone run --account-id acc_123 --profile production --debug --output-file result.json
Run with builtin (StackOne) connector version:
stackone run --connector my-provider@1.0.0 --account-id acc_123 --profile production --builtin
Run with custom (organization) connector version:
stackone run --connector my-provider@1.0.0 --account-id acc_123 --profile production --custom
Run with explicit owner for version disambiguation:
stackone run --connector my-provider@1.0.0 --account-id acc_123 --profile production --owner my-org
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": "john@example.com"
}
}
All fields are optional and default to empty objects {}.
Requirements:
--account or --account-id must be provided--account-id, either --profile or --api-key is requiredprovider_key@version or provider_key), either --profile or --api-key is required--profile or --api-key, not both--action, the --connector option is required--connector with a file path or inline YAML--connector with identifier format (provider_key@version) to fetch from registry--account-id without --connectorFeatures:
provider_key@version, provider_key for latest, or version wildcards (e.g., 1.x.x or latest), or auto-fetch from API using account IDversionShow CLI version information. If a new version is available, it will prompt you to update:
stackone version
--versionShow the current version of the CLI:
stackone --version
stackone -v
updateUpdate 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 versionUsage Examples:
Check and update to latest version:
stackone update
Force reinstall (useful for fixing corrupted installations):
stackone update --force
Features:
--force is used)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.0.0 → 1.1.0)If you're already on the latest version, the command will confirm this and exit without making changes (unless you use the --force flag).
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.
# Authenticate with StackOne
stackone agent setup
# Start interactive chat
stackone agent chat --mode build
agent chatStart 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 loggingFeatures:
agent setupSetup the StackOne agent. This command can be used for global authentication or local project configuration.
Global setup (default) - Initialize and authenticate the StackOne agent globally:
stackone agent setup
# equivalent to:
stackone agent setup --global
By default the command opens a browser-based device-code flow — sign in to StackOne in the browser and the CLI picks up the resulting token automatically. Pass --legacy to fall back to an interactive email/password prompt.
For programmatic / CI use, the legacy flow can run non-interactively. Pass --legacy to opt in (env vars and credential flags are only honored when --legacy is set). Email comes from --email or STACKONE_EMAIL; password comes from --password-stdin (preferred), --password, or STACKONE_PASSWORD:
# env vars
STACKONE_EMAIL=me@stackone.com STACKONE_PASSWORD=$SECRET stackone agent setup --legacy
# pipe password from a secret manager
vault read -field=pw secret/stackone | \
stackone agent setup --legacy --email me@stackone.com --password-stdin
--password puts the password in argv (visible to other processes via ps and shell history) — prefer --password-stdin or env vars wherever possible.
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
If you aren't already authenticated globally, the command will launch the same auth flow first. It then writes an .mcp.json in the current directory with a local MCP server entry pointing at your token. The MCP configuration uses the STACKONE_AGENT_MCP_TOKEN environment variable, which is automatically managed by the agent setup command.
Options:
-g, --global - Setup global configuration (default)-l, --local - Setup local project configuration--legacy - Use email/password login instead of browser-based auth--email <email> - Email for legacy login (or set STACKONE_EMAIL); requires --legacy--password <password> - Password for legacy login (or set STACKONE_PASSWORD); requires --legacy. Prefer --password-stdin--password-stdin - Read password for legacy login from stdin; requires --legacyagent cleanupRemove all API keys and credentials from agent configurations. This command:
~/.stackone/agent-config.json (global auth config).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.
# 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
npm run build
npm test
The package is configured to be published to NPM with public access:
npm run publish-release
The agent commands use @stackone/agent-harness - a composable agent runtime:
Framework:
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:
Why Anthropic SDK directly?
FAQs
StackOne Connect CLI tool
The npm package @stackone/cli receives a total of 992 weekly downloads. As such, @stackone/cli popularity was classified as not popular.
We found that @stackone/cli demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Laravel Lang packages were compromised with an RCE backdoor across hundreds of versions, exposing cloud, CI/CD, and developer secrets.
Security News
Socket found a malicious postinstall hook across 700+ GitHub repos, including PHP packages on Packagist and Node.js project repositories.
Security News
Vibe coding at scale is reshaping how packages are created, contributed, and selected across the software supply chain