stackonehq/stackone-cli

StackOne CLI — Connector Development

Important

The CLI is actively developed and commands change between versions. Before providing CLI guidance:

1. Fetch https://docs.stackone.com/guides/connector-engine/cli-reference for the current command reference
2. Fetch https://www.npmjs.com/package/@stackone/cli for the latest version

Do not guess CLI commands or flags — always verify against live docs.

Instructions

Step 1: Install the CLI

npm install -g @stackone/cli

This installs the global stackone command. Verify with stackone --version.

Step 2: Understand when to build a custom connector

Custom connectors are for platforms that StackOne doesn't natively support. Before building one:

• Check if the provider already exists: use the stackone-connectors skill or browse https://docs.stackone.com/connectors/introduction
• If the provider exists but is missing specific actions, you may not need a full custom connector — check the Actions RPC endpoint first

Step 3: Initialize a connector project

Fetch the connector structure guide for the current project layout: https://docs.stackone.com/guides/connector-engine/connector-structure

The Connector Engine provides:

• Project scaffolding
• Local development server for testing
• Type-safe action definitions
• Deployment tooling

Step 4: Use the AI Builder (optional)

The AI Builder can generate connector scaffolding from API documentation. Fetch the guide: https://docs.stackone.com/guides/connector-engine/ai-builder

This accelerates development by generating boilerplate from an OpenAPI spec or API docs URL.

Step 5: Test locally

Run the connector locally to test against the target API before deploying. Fetch the CLI reference for the exact test commands: https://docs.stackone.com/guides/connector-engine/cli-reference

Step 6: Deploy

Deploy to StackOne's infrastructure. For automated deployments, set up CI/CD: https://docs.stackone.com/guides/connector-engine/github-workflow

Examples

Example 1: User wants to build a connector for an internal API

User says: "We have an internal HR system. Can I connect it to StackOne?"

Actions:

1. Confirm the internal API has a REST/GraphQL endpoint
2. Install the CLI: npm install -g @stackone/cli
3. Fetch the connector structure guide for the scaffolding command
4. If they have an OpenAPI spec, suggest the AI Builder for faster scaffolding
5. Walk through the init → develop → test → deploy flow

Result: Custom connector project initialized with the right structure.

Example 2: User wants to set up CI/CD for connector deployment

User says: "How do I auto-deploy connectors from GitHub?"

Actions:

1. Fetch https://docs.stackone.com/guides/connector-engine/github-workflow
2. Walk through the GitHub Actions workflow configuration
3. Explain the deployment stages (dev → staging → production)

Result: Working GitHub Actions pipeline for connector deployment.

Troubleshooting

CLI command not found after install

Cause: Global npm bin directory not in PATH.

• Run npm config get prefix to find the install location
• Add {prefix}/bin to your PATH
• Alternatively, use npx @stackone/cli instead of the global command

Authentication failures in CLI

Cause: Missing or invalid credentials.

• The CLI requires a StackOne API key
• Fetch the CLI reference for the current auth setup command
• Verify the key is active at https://app.stackone.com

Connector deployment fails

Cause: Various — check the error message.

• Fetch the CLI reference for deployment troubleshooting
• Common issues: missing required fields in connector config, network timeouts
• For CI/CD failures, check that secrets are correctly configured in GitHub Actions

Related Skills

• stackone-unified-connectors: For building schema-based connectors that transform provider data into standardized schemas with field mapping, enum translation, and unified pagination
• stackone-connectors: For discovering existing connector capabilities
• stackone-agents: For building AI agents that use connectors