# 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:

```bash
poetry install
```

## Usage

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

### General Syntax

```bash
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.

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

**Arguments:**
- `--file, -f`: Path to JSON file containing software metadata (required)

**Example:**
```bash
ska-src-software-discovery register --file examples/sample_software_metadata.json
```

#### 2. Update Existing Software

Update existing software metadata.

```bash
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:**
```bash
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.

```bash
ska-src-software-discovery health
```

**Example:**
```bash
ska-src-software-discovery health
```

#### 4. Ping API

Check if the API is alive and responding.

```bash
ska-src-software-discovery ping
```

**Example:**
```bash
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:

```bash
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:

```json
{
  "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:

```json
{
  "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:

```bash
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:
```bash
ska-src-software-discovery register --file my-software-v1.0.0.json
```

2. Update the software metadata:
```bash
ska-src-software-discovery update --software-id "urn:ska:software:my-app@1.0.0" --file my-software-v1.0.1.json
```

3. Check API health:
```bash
ska-src-software-discovery health
```

## Getting Help

For help on any command:

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