aspera-cli 4.26.2 → 4.27.1

data/lib/aspera/cli/options.schema.yaml

@@ -6,9 +6,95 @@ info:
 paths: {}
 components:
   schemas:
-    TransferInfo:
+    LogOptions:
       type: object
-      description: Optional parameters to control multi-session transfers, Web Socket Session, resume policy, and additional arguments for `ascp`.
+      description: Logging options.
+      properties:
+        level:
+          type: string
+          description: Minimum log level displayed.
+          enum: [trace2, trace1, debug, info, warn, error, fatal, unknown]
+          default: warn
+        type:
+          type: string
+          description: Log output destination.
+          enum: [stderr, stdout, syslog]
+          default: stderr
+        format:
+          type: string
+          description: Log line formatter. Use `@ruby:` for a custom lambda.
+          enum: [default, caller, standard]
+          default: default
+        secrets:
+          type: boolean
+          description: Show passwords and secrets in logs.
+          default: false
+    McpServerOptions:
+      type: object
+      description: MCP server configuration for the `mcp server` command.
+      properties:
+        transport:
+          type: string
+          description: Transport used by the MCP server.
+          enum: [stdio, http]
+          default: stdio
+        extra_args:
+          type: array
+          description: Flags prepended to every `ascli` command.
+          items:
+            type: string
+        max_text_bytes:
+          type: integer
+          description: Maximum number of bytes for JSON text content in list results.
+          default: 100000
+        max_line_bytes:
+          type: integer
+          description: Maximum JSON frame size for stdio transport.
+          default: 4194304
+        port:
+          type: integer
+          description: TCP port for HTTP transport.
+          default: 3000
+        bind:
+          type: string
+          description: Bind address for HTTP transport.
+          default: 127.0.0.1
+        stateless:
+          type: boolean
+          description: Run HTTP transport in stateless mode.
+          default: false
+        allowed_origins:
+          type: array
+          description: Allowed HTTP origin values.
+          items:
+            type: string
+        allowed_hosts:
+          type: array
+          description: Allowed HTTP host values.
+          items:
+            type: string
+        session_idle_timeout:
+          type: integer
+          description: HTTP session idle timeout in seconds.
+        max_sessions:
+          type: integer
+          description: Maximum number of HTTP sessions.
+        instructions:
+          type: string
+          description: Instructions shown to the AI client.
+        description:
+          type: string
+          description: Description advertised by the MCP server.
+        protocol_version:
+          type: string
+          description: MCP protocol version, for example `2024-11-05`.
+        validate_tool_call_arguments:
+          type: boolean
+          description: Validate MCP tool call arguments.
+          default: true
+    DirectAgentOptions:
+      type: object
+      description: Parameters for the `ascp` transfer agent.
       properties:
         wss:
           type: boolean
@@ -17,7 +103,14 @@ components:
         quiet:
           type: boolean
           description: Suppress the `ascp` progress bar display.
-          default: false
+          default: true
+        file_list:
+          type: boolean
+          description: >-
+            If `true`, source paths are written to a temp file passed to `ascp` via `--file-list` or `--file-pair-list`.
+
+            If `false`, source paths are placed directly on the `ascp` command line.
+          default: true
         trusted_certs:
           type: array
           description: List of trusted certificate repositories.
@@ -41,7 +134,7 @@ components:
           type: number
           format: float
           description: Multi session - Maximum time (in seconds) to verify that `ascp` is running.
-          default: 3
+          default: 2
         spawn_delay_sec:
           type: number
           format: float
@@ -51,11 +144,12 @@ components:
           type: boolean
           description: >-
             Multi session - Increment UDP port for each session.
-            
+
             If `true`, each session uses a different UDP port starting at `fasp_port` (default: 33001).
-            
+
             If `false`, all sessions use the same `fasp_port` (or `ascp` default).
-          default: true
+
+            Default: `true` on Windows, `false` on other platforms.
         resume:
           type: object
           description: Configuration for automatic transfer resume on interruption.
@@ -80,3 +174,536 @@ components:
           type: boolean
           description: Enable use of the `ascp` management port for transfer monitoring.
           default: true
+    NodeAgentOptions:
+      type: object
+      description: Parameters for the Node API transfer agent.
+      required:
+        - url
+        - username
+        - password
+      properties:
+        url:
+          type: string
+          description: URL of the Node API.
+        username:
+          type: string
+          description: Node API user or access key.
+        password:
+          type: string
+          description: Password, secret, or bearer token.
+        root_id:
+          type: string
+          description: Root file ID. Mandatory only when `password` is a bearer token.
+    HttpgwAgentOptions:
+      type: object
+      description: Parameters for the HTTP Gateway transfer agent.
+      required:
+        - url
+      properties:
+        url:
+          type: string
+          description: URL of the HTTP Gateway.
+        upload_chunk_size:
+          type: integer
+          description: Size in bytes of each upload chunk.
+          default: 64000
+        api_version:
+          type: string
+          description: Force use of a specific API version.
+          enum:
+            - v1
+            - v2
+          default: v2
+        synchronous:
+          type: boolean
+          description: Wait for acknowledgment after each message.
+          default: false
+    DesktopAgentOptions:
+      type: object
+      description: >-
+        Parameters for the IBM Aspera Desktop Client transfer agent.
+        The Desktop Client must be running locally. No additional options are required.
+      properties: {}
+    ConnectAgentOptions:
+      type: object
+      description: >-
+        Parameters for the IBM Aspera Connect Client transfer agent.
+        The Connect Client must be running locally. No additional options are required.
+      properties: {}
+    TransferdAgentOptions:
+      type: object
+      description: Parameters for the Transfer Daemon transfer agent.
+      properties:
+        url:
+          type: string
+          description: >-
+            Address and port listened by the daemon (e.g. `:55002`).
+            If port is `0`, the daemon listens on a random available port.
+            If no address is given, `127.0.0.1` is used.
+          default: ":0"
+        start:
+          type: boolean
+          description: Start a new daemon instance.
+          default: true
+        stop:
+          type: boolean
+          description: Stop the daemon when `ascli` exits.
+          default: true
+    TransferAgentOptions:
+      description: >-
+        Transfer agent selector and agent-specific parameters.
+        Set `agent` to select the agent type (default: `direct`).
+        Remaining keys are passed to the selected agent.
+      oneOf:
+        - $ref: "#/components/schemas/DirectAgentOptions"
+        - $ref: "#/components/schemas/NodeAgentOptions"
+        - $ref: "#/components/schemas/HttpgwAgentOptions"
+        - $ref: "#/components/schemas/TransferdAgentOptions"
+        - $ref: "#/components/schemas/DesktopAgentOptions"
+        - $ref: "#/components/schemas/ConnectAgentOptions"
+      discriminator:
+        propertyName: agent
+        mapping:
+          direct: "#/components/schemas/DirectAgentOptions"
+          node: "#/components/schemas/NodeAgentOptions"
+          httpgw: "#/components/schemas/HttpgwAgentOptions"
+          transferd: "#/components/schemas/TransferdAgentOptions"
+          desktop: "#/components/schemas/DesktopAgentOptions"
+          connect: "#/components/schemas/ConnectAgentOptions"
+    SmtpOptions:
+      type: object
+      description: SMTP email server configuration.
+      required:
+        - server
+      properties:
+        server:
+          type: string
+          description: SMTP server address.
+          example: smtp.gmail.com
+        tls:
+          type: boolean
+          description: Enable `STARTTLS` (port 587).
+          default: true
+        ssl:
+          type: boolean
+          description: Enable `TLS/SSL` (port 465).
+          default: false
+        port:
+          type: integer
+          description: >-
+            Port for the SMTP service.
+
+            Defaults: `587` (TLS), `465` (SSL), `25` (plain).
+          example: 587
+        domain:
+          type: string
+          description: Email domain of the user. Defaults to the domain part of `server`.
+          example: gmail.com
+        username:
+          type: string
+          description: >-
+            User to authenticate on the SMTP server.
+            Leave empty for open (unauthenticated) relay.
+          example: john@example.com
+        password:
+          type: string
+          description: Password for the above `username`.
+          example: my_password
+        from_email:
+          type: string
+          description: Sender address (used in `From:` header and as reply-to). Defaults to `username` when defined.
+          example: johnny@example.com
+        from_name:
+          type: string
+          description: Display name of the sender. Defaults to the local-part of `from_email`.
+          example: John Wayne
+    HttpOptions:
+      type: object
+      description: >-
+        HTTP/S connection parameters for REST calls (not `ascp` WSS).
+
+        Keys are dispatched at startup to three targets:
+        `RestParameters` (`user_agent`, `download_partial_suffix`, `retry_*`),
+        `SSL` (`ssl_options`), and `OAuth` (`token_cache_max_age`, `token_refresh_threshold`).
+        Any remaining key is forwarded as a setter to the `Net::HTTP` session
+        (e.g. `ca_file`, `verify_mode`) — the list below covers the common ones.
+      additionalProperties: true
+      properties:
+        read_timeout:
+          type: number
+          description: Maximum time in seconds to wait for data to be read from the server. (Net::HTTP)
+          default: 60
+        write_timeout:
+          type: number
+          description: Maximum time in seconds to wait for data to be written to the server. (Net::HTTP)
+          default: 60
+        open_timeout:
+          type: number
+          description: Maximum time in seconds to wait for a connection to be established. (Net::HTTP)
+          default: 60
+        keep_alive_timeout:
+          type: number
+          description: Maximum time in seconds to keep an idle persistent connection open. (Net::HTTP)
+          default: 2
+        ssl_options:
+          type: array
+          description: List of OpenSSL option flags to set on the HTTP session (e.g. `IGNORE_UNEXPECTED_EOF`). (SSL)
+          items:
+            type: string
+        user_agent:
+          type: string
+          description: Value sent in the `User-Agent` HTTP request header. (Rest)
+        download_partial_suffix:
+          type: string
+          description: File suffix appended to the target filename while a download is in progress. (Rest)
+          default: .http_partial
+        retry_on_error:
+          type: boolean
+          description: Retry the request on any HTTP error response. (Rest)
+          default: false
+        retry_on_timeout:
+          type: boolean
+          description: Retry the request on connection timeout. (Rest)
+          default: true
+        retry_on_unavailable:
+          type: boolean
+          description: Retry the request on HTTP 503 Service Unavailable. (Rest)
+          default: true
+        retry_max:
+          type: integer
+          description: Maximum number of retry attempts. (Rest)
+          default: 1
+        retry_sleep:
+          type: integer
+          description: Delay in seconds between retry attempts. (Rest)
+          default: 4
+        token_cache_max_age:
+          type: integer
+          description: Maximum age in seconds of a cached OAuth token before it is discarded. (OAuth)
+          default: 1800
+        token_refresh_threshold:
+          type: integer
+          description: Remaining token lifetime in seconds below which the token is proactively refreshed. (OAuth)
+          default: 120
+    VaultHashicorpOptions:
+      type: object
+      description: IBM HashiCorp Vault secret store.
+      required:
+        - type
+        - url
+      properties:
+        type:
+          type: string
+          description: Vault type selector.
+          enum: [vault]
+        url:
+          type: string
+          description: URL of the HashiCorp Vault server.
+          example: "http://127.0.0.1:8200"
+        token:
+          type: string
+          description: Authentication token. Defaults to the value of `vault_password`.
+          example: dev-only-token
+    VaultSystemOptions:
+      type: object
+      description: macOS system keychain secret store.
+      required:
+        - type
+      properties:
+        type:
+          type: string
+          description: Vault type selector.
+          enum: [system]
+        name:
+          type: string
+          description: Name of the keychain to use.
+    VaultOnePasswordOptions:
+      type: object
+      description: 1Password secret store (Connect REST API or CLI).
+      required:
+        - type
+        - source
+      properties:
+        type:
+          type: string
+          description: Vault type selector.
+          enum: [1password]
+        source:
+          type: string
+          description: Backend source. Use `api` for the Connect REST API, `cli` for the `op` CLI.
+          enum: [api, cli]
+          default: api
+        url:
+          type: string
+          description: Base URL of the 1Password Connect server (required when `source` is `api`).
+          example: "http://localhost:8080"
+        vault_id:
+          type: string
+          description: ID of the 1Password vault to use (required when `source` is `api`).
+        token:
+          type: string
+          description: Bearer token for the Connect API (required when `source` is `api`). Defaults to the value of `vault_password`.
+        vault:
+          type: string
+          description: Name or ID of the 1Password vault to use with the CLI (used when `source` is `cli`). Uses the default vault if omitted.
+        account:
+          type: string
+          description: Account shorthand for `op` (used when `source` is `cli`). Uses the default account if omitted.
+    VaultFileOptions:
+      type: object
+      description: Encrypted file secret store.
+      required:
+        - type
+      properties:
+        type:
+          type: string
+          description: Vault type selector.
+          enum: [file]
+        name:
+          type: string
+          description: >-
+            Path to the encrypted vault file.
+            Relative paths are resolved from the configuration folder.
+          default: vault.bin
+    VaultSecret:
+      type: object
+      description: Secret entry in the vault
+      required:
+        - label
+      properties:
+        label:
+          type: string
+          description: Unique identifier for this secret entry
+        username:
+          type: string
+          description: Username associated with the secret
+        password:
+          type: string
+          description: Secret value
+        url:
+          type: string
+          description: URL associated with the secret
+        description:
+          type: string
+          description: Human-readable description of this secret
+    VaultOptions:
+      title: Secret vault configuration
+      description: Secret vault configuration. Set `type` to select the vault backend.
+      oneOf:
+        - $ref: "#/components/schemas/VaultHashicorpOptions"
+        - $ref: "#/components/schemas/VaultSystemOptions"
+        - $ref: "#/components/schemas/VaultFileOptions"
+        - $ref: "#/components/schemas/VaultOnePasswordOptions"
+      discriminator:
+        propertyName: type
+        mapping:
+          vault:      "#/components/schemas/VaultHashicorpOptions"
+          system:     "#/components/schemas/VaultSystemOptions"
+          file:       "#/components/schemas/VaultFileOptions"
+          1password:  "#/components/schemas/VaultOnePasswordOptions"
+    ImageOptions:
+      type: object
+      description: Options for displaying images and thumbnails in the terminal.
+      properties:
+        reserve:
+          type: integer
+          description: Number of terminal lines reserved for non-image output.
+          default: 3
+        text:
+          type: boolean
+          description: Display the image as colorized text instead of using the iTerm2 inline protocol.
+          default: false
+        double:
+          type: boolean
+          description: Use double vertical resolution via half-block characters.
+          default: true
+        font_ratio:
+          type: number
+          format: float
+          description: Terminal font aspect ratio (height divided by width).
+          default: 2.3
+    PackageFolderOptions:
+      type: object
+      title: Package download folder organization
+      description: >-
+        Controls how downloaded packages are organized into subfolders under `to_folder`.
+        If not specified or empty, packages are downloaded directly into `to_folder`.
+      properties:
+        fld:
+          type: array
+          description: >-
+            List of package fields (up to 2) used to build the subfolder name.
+            Field values are joined with `.`.
+          items:
+            type: string
+          maxItems: 2
+          example: ["name", "id"]
+        seq:
+          type: boolean
+          description: >-
+            If `true`, appends an incrementing number to the folder name when a conflict occurs.
+          default: false
+        opt:
+          type: boolean
+          description: >-
+            If `false` (default), all fields in `fld` are always used.
+            If `true`, the first field is used unless the folder already exists.
+          default: false
+        inf:
+          type: boolean
+          description: >-
+            If `true`, creates a `<ID>.info.json` sidecar file inside the folder
+            containing package metadata.
+          default: false
+    NodeBearerTokenOptions:
+      type: object
+      description: >-
+        JWT payload used to generate an Aspera Node bearer token (`node bearer_token`).
+        `user_id` is the only mandatory field.
+        The CLI strips the `_validity` and `_scope` convenience keys before signing;
+        remaining fields are embedded verbatim in the token.
+      required:
+        - user_id
+      properties:
+        user_id:
+          type: string
+          description: Identifier of the user for whom the token is generated.
+          example: jdoe
+        _validity:
+          type: integer
+          description: Token lifetime in seconds (convenience key, removed before signing).
+          default: 86400
+        _scope:
+          type: string
+          description: >-
+            Scope shorthand used to build the `scope` field (convenience key, removed before signing).
+            Maps to `node.<access_key>:<scope>`.
+          enum: [user, admin]
+          default: user
+        scope:
+          type: string
+          description: >-
+            Full scope string. Computed automatically from `_scope` when absent.
+            Example: `node::ik-00000000-0000-0000-0000-000000000000:user`.
+        auth_type:
+          type: string
+          description: Authentication type embedded in the token.
+          default: access_key
+        expires_at:
+          type: string
+          description: >-
+            Token expiry timestamp in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`).
+            Computed automatically from `_validity` when absent.
+          example: "2030-01-01T00:00:00Z"
+    NodeSimulatorOptions:
+      type: object
+      description: >-
+        Configuration for the embedded Node API simulator (`node simulator`).
+        The simulator starts a local WEBrick server that answers `/ops/transfers`,
+        `/ops/transfers/{id}`, `/files/browse`, and `/info` — sufficient to test
+        CLI commands against a live Node API without a real HSTS instance.
+      properties:
+        url:
+          type: string
+          description: >-
+            Address and port the simulator listens on.
+            Use `https://` with `cert`/`key` for TLS.
+          default: http://localhost:8080
+        cert:
+          type: string
+          description: >-
+            Path to the TLS certificate file.
+            Accepted formats: PEM (`.pem`) or PKCS12 (`.p12` / `.pfx`).
+          example: /path/to/cert.pem
+        key:
+          type: string
+          description: >-
+            Path to the PEM private key file, or the PKCS12 passphrase when `cert` is a `.p12`/`.pfx` file.
+          example: /path/to/key.pem
+        chain:
+          type: string
+          description: Path to the PEM certificate chain file (appended as extra chain certificates).
+          example: /path/to/chain.pem
+        browse_root:
+          type: string
+          description: >-
+            Root directory the simulator is allowed to expose via `/files/browse`.
+            Requests for paths outside this directory are rejected.
+            Defaults to the current working directory.
+          example: /data/aspera
+    NodeTelemetryOptions:
+      type: object
+      description: >-
+        Configuration for the telemetry reporter (`node telemetry`).
+        The command periodically queries `ops/transfers?active_only=true` and sends
+        an OpenTelemetry gauge metric to an Instana backend.
+      required:
+        - url
+        - key
+      properties:
+        url:
+          type: string
+          description: Base URL of the Instana backend (without `/v1`).
+          example: https://my-instana.example.com
+        key:
+          type: string
+          description: Instana API key sent in the `x-instana-key` header.
+          example: my-instana-api-key
+        interval:
+          type: number
+          format: float
+          description: >-
+            Polling interval in seconds. Use `0` for a single-shot run (no loop).
+          default: 10
+        hostname:
+          type: string
+          description: >-
+            Value sent in the `x-instana-host` header.
+            Defaults to the local machine's hostname.
+          example: hsts-prod-01
+    TableOptions:
+      type: object
+      description: Terminal table rendering options.
+      properties:
+        pivot:
+          type: string
+          description: Control how an object list is displayed (no/yes/single).
+          enum: ['no', 'yes', 'single']
+          default: 'no'
+    OutOptions:
+      type: object
+      description: Output rendering options (dot-notation sub-properties).
+      properties:
+        format:
+          type: string
+          description: Output format.
+          enum: [text, nagios, ruby, json, jsonpp, yaml, table, csv, image]
+          default: table
+        level:
+          type: string
+          description: Output verbosity level (which information to display).
+          enum: [info, data, error]
+          default: data
+        file:
+          type: string
+          description: Destination file for results (use `-` for stdout).
+        fields:
+          description: >-
+            Comma-separated list of fields to display, or a special value:
+            `ALL` for all fields, `DEF` for default fields.
+            Prefix a field name with `-` to exclude it.
+        select:
+          type: object
+          description: Select only matching items from a list (field/value filter or lambda).
+        table:
+          $ref: "#/components/schemas/TableOptions"
+        flat:
+          type: boolean
+          description: Display deep hash values as additional top-level keys.
+          default: true
+        secrets:
+          type: boolean
+          description: Show secrets in command output.
+          default: false
+        img:
+          $ref: "#/components/schemas/ImageOptions"