SKA Software Discovery CLI

A command-line interface for interacting with the SKA Software Discovery API.

Installation

The CLI is available in the bin directory of this repository. To use it, ensure you have the required dependencies installed:

poetry install

Usage

The CLI provides several commands for interacting with the Software Discovery API.

General Syntax

ska-src-software-discovery [--api-url API_URL] <command> [options]

Options:

  • --api-url: The base URL of the Software Discovery API (default: https://software-discovery.ral-preprod.uksrc.org/api/v1)

Commands

1. Register New Software

Register new software metadata with the API.

ska-src-software-discovery register --file <path-to-json-file>

Arguments:

  • --file, -f: Path to JSON file containing software metadata (required)

Example:

ska-src-software-discovery register --file examples/sample_software_metadata.json

2. Update Existing Software

Update existing software metadata.

ska-src-software-discovery update --software-id <software-id> --file <path-to-json-file>

Arguments:

  • --software-id, -id: Software identifier to update (required)

  • --file, -f: Path to JSON file containing updated software metadata (required)

Example:

ska-src-software-discovery update --software-id "urn:ska:software:example-app@1.0.0" --file examples/sample_software_metadata.json

3. Check API Health

Check the health status of the API and its dependent services.

ska-src-software-discovery health

Example:

ska-src-software-discovery health

4. Ping API

Check if the API is alive and responding.

ska-src-software-discovery ping

Example:

ska-src-software-discovery ping

Delete API

The current CLI does not provide a dedicated delete command yet. To delete software metadata, call the API directly:

curl -X DELETE "https://software-discovery.ral-preprod.uksrc.org/api/v1/registrations/<registration-id>" \
  -H "Authorization: Bearer <token>"

Replace <registration-id> with the UUID returned when the software was ingested, for example 123e4567-e89b-12d3-a456-426614174000.

Expected response:

{
  "registration_id": "123e4567-e89b-12d3-a456-426614174000",
  "message": "Software '123e4567-e89b-12d3-a456-426614174000' deleted successfully."
}

Software Metadata Format

The software metadata JSON file must follow the SoftwareMetadata schema. Here’s an example:

{
  "uri": "ska:software:example-app@1.0.0",
  "description": "A sample software application for demonstration purposes",
  "release_date": "2026-03-10T12:00:00Z",
  "changelog": "Initial release with basic features",
  "status": "STABLE",
  "discovery": {
    "science_category": ["astronomy", "data-processing"],
    "function_category": ["imaging", "analysis"],
    "science_working_group": ["eor", "cosmology"],
    "tools_included": ["numpy", "scipy", "astropy"]
  },
  "data_compatibility": {
    "data_input_type": ["FITS", "HDF5", "MS"],
    "data_output_type": ["FITS", "PNG", "JSON"]
  },
  "resources": {
    "requires_gpu": false,
    "min_memory": 4,
    "recommended_memory": 8
  },
  "provenance": {
    "repository_url": "https://github.com/skao/example-app",
    "registered_by": "user@example.com",
    "registration_date": "2026-03-10T12:00:00Z"
  },
  "artifacts": [
    {
      "kind": "DOCKER",
      "location": "https://registry.example.com/example-app:1.0.0",
      "cpu_architecture": ["x86_64", "arm64"],
      "digest": "sha256:abcdef1234567890",
      "entrypoint": "/usr/local/bin/example-app",
      "supported_modes": ["HEADLESS", "DESKTOP"]
    }
  ]
}

Required Fields

  • uri: Unique URI for the software (format: {publisher}:{name}:{semver}, e.g., ska:example-app:1.0.0)

  • artifacts: At least one artifact required

  • artifacts[].kind: One of: DOCKER, SINGULARITY, OCI

  • artifacts[].location: Non-empty string

  • artifacts[].cpu_architecture: At least one of: amd64, arm64

Optional Fields

  • description: Detailed description of the software

  • release_date: IVOA DALI UTC timestamp (e.g., 2026-03-10T12:00:00Z)

  • changelog: Summary of changes in this version

  • status: One of: ALPHA, BETA, TESTING, STABLE, DEPRECATED

  • discovery: Discovery metadata (science categories, functions, etc.)

  • data_compatibility: Input and output data types

  • resources: Resource requirements (GPU, memory)

  • provenance: Repository URL, registered by, registration date

  • artifacts[].digest: Format: sha256:<64 hex chars>

  • artifacts[].entrypoint: Command to run

  • artifacts[].supported_modes: Array of: NOTEBOOK, DESKTOP, HEADLESS

Using with Custom API URL

To use with a different API endpoint:

ska-src-software-discovery --api-url https://custom-api.example.com/api/v1 register --file metadata.json

Error Handling

The CLI will:

  • Display error messages from the API if requests fail

  • Return proper exit codes for scripting purposes

  • Pretty-print JSON responses for readability

Examples

Complete Workflow

  1. Register a new software version:

ska-src-software-discovery register --file my-software-v1.0.0.json

  1. Update the software metadata:

ska-src-software-discovery update --software-id "urn:ska:software:my-app@1.0.0" --file my-software-v1.0.1.json

  1. Check API health:

ska-src-software-discovery health

Getting Help

For help on any command:

ska-src-software-discovery --help
ska-src-software-discovery register --help
ska-src-software-discovery update --help