@stackone/cli 1.11.0 → 1.12.0

package/README.md

@@ -130,6 +130,88 @@ stackone drop <connector> --api-key <your-api-key> --api-url <api-url>
 - **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.
+
+```bash
+stackone get --connector my-provider@1.0.0 --profile <profile-label>
+```
+
+or using direct credentials:
+
+```bash
+stackone get --connector my-provider@1.0.0 --api-key <your-api-key>
+```
+
+or fetch from an account:
+
+```bash
+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`)
+- `--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:**
+
+   ```bash
+   stackone get --connector my-provider@1.0.0 --profile production
+   ```
+
+2. **Get connector from registry with API key:**
+
+   ```bash
+   stackone get --connector my-provider@1.0.0 --api-key your-api-key
+   ```
+
+3. **Get connector from account:**
+
+   ```bash
+   stackone get --account-id acc_123 --profile production
+   ```
+
+4. **Get connector in JSON format:**
+
+   ```bash
+   stackone get --connector my-provider@1.0.0 --profile production --format json
+   ```
+
+5. **Get connector and save to file:**
+
+   ```bash
+   stackone get --connector my-provider@1.0.0 --profile production --output-file my-connector.s1.yaml
+   ```
+
+6. **Get connector with custom API URL:**
+
+   ```bash
+   stackone get --connector my-provider@1.0.0 --api-key your-api-key --api-url https://staging.api.stackone.com
+   ```
+
+**Features:**
+
+- **Flexible authentication**: Use either a saved profile or provide credentials directly
+- **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:
@@ -158,57 +240,97 @@ Execute a connector action locally with full control over connector configuratio
 stackone run --connector path/to/connector.s1.yaml --account-id <account-id> --profile <profile-label>
 ```
 
+or using direct credentials:
+
+```bash
+stackone run --account-id <account-id> --api-key <your-api-key>
+```
+
 **Options:**
 
-- `--connector <connector>` - Path to the connector file to run, or inline connector YAML string
+- `--connector <connector>` - Path to the connector file to run, inline connector YAML string, or connector identifier in format `provider_key@version` 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 `--profile`)
+- `--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 (required when using `--account-id`)
+- `-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:**
+1. **Run with account from API using profile (connector fetched automatically):**
 
    ```bash
-   stackone run --connector connector.s1.yaml --account-id acc_123 --profile production
+   stackone run --account-id acc_123 --profile production
    ```
 
-2. **Run with local account file & credentials:**
+2. **Run with account from API using API key (connector fetched automatically):**
 
    ```bash
-   stackone run --connector connector.s1.yaml --account account.json --credentials credentials.json
+   stackone run --account-id acc_123 --api-key your-api-key
    ```
 
-3. **Run with inline account data:**
+3. **Run with custom API URL:**
 
    ```bash
-   stackone run --connector connector.s1.yaml --account '{"auth_config_key":"basic","credentials":{"username":"user","password":"pass"}}'
+   stackone run --account-id acc_123 --api-key your-api-key --api-url https://staging.api.stackone.com
    ```
 
-4. **Run specific action with parameters:**
+4. **Run with connector identifier from registry:**
 
    ```bash
-   stackone run --connector connector.s1.yaml --action-id list_employees --account-id acc_123 --profile production --params params.json
+   stackone run --connector my-provider@1.0.0 --account account.json --api-key your-api-key
    ```
 
-5. **Run with custom action file:**
+5. **Run with connector from registry and account from API:**
 
    ```bash
-   stackone run --connector connector.s1.yaml --action custom-action.yaml --account account.json
+   stackone run --connector my-provider@1.0.0 --account-id acc_123 --profile production
    ```
 
-6. **Run with debug mode and output to file:**
+6. **Run with account from API and specific connector file:**
 
    ```bash
-   stackone run --connector connector.s1.yaml --account-id acc_123 --profile production --debug --output-file result.json
+   stackone run --connector connector.s1.yaml --account-id acc_123 --profile production
    ```
 
+7. **Run with local account file & credentials:**
+
+   ```bash
+   stackone run --connector connector.s1.yaml --account account.json --credentials credentials.json
+   ```
+
+8. **Run with inline account data:**
+
+   ```bash
+   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):**
+
+   ```bash
+   stackone run --action-id list_employees --account-id acc_123 --api-key your-api-key --params params.json
+   ```
+
+10. **Run with custom action file:**
+
+    ```bash
+    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):**
+
+    ```bash
+    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:
@@ -267,13 +389,19 @@ All fields are optional and default to empty objects `{}`.
 **Requirements:**
 
 - Either `--account` or `--account-id` must be provided
-- When using `--account-id`, the `--profile` option is required
+- When using `--account-id`, either `--profile` or `--api-key` is required
+- When using connector identifier format (`provider_key@version`), 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 valid connector is required (via `--connector` or inferred from action)
+- 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 or provide inline YAML
+- **Flexible connector loading**: Load from file path, provide inline YAML, fetch from registry using `provider_key@version` identifier, 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

package/dist/cli.cjs

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-const e=require(`./cliCore-CXBqMdiv.cjs`),t=new e.CLI;t.run();
+const e=require(`./cliCore-CdUkuL9P.cjs`),t=new e.CLI;t.run();

package/dist/cli.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-import{CLI as e}from"./cliCore-DRnQtnk3.js";const t=new e;t.run();
+import{CLI as e}from"./cliCore-C6WfW_Zy.js";const t=new e;t.run();