Skip to content

Command line

The CLI is useful for inspecting a service, keeping execution requests in files, and integrating submissions into scripts. This walkthrough uses the local test service, an active pixi shell, and the repository root as the working directory.

The commands are maintained in examples/guides/cli.sh. Copy individual recipes; running that file does not submit jobs. Commands shown on a single line work in Bash and PowerShell.

Configure and inspect the service

s2gos-client configure --api-url http://127.0.0.1:8008 --auth-type none --config local-client.yaml
s2gos-client list-processes --config local-client.yaml
s2gos-client get-process primes_between --config local-client.yaml

The profile contains the API URL and authentication settings. --config belongs to the individual command, after its name. For a hosted deployment, create and log in to a separate profile as described in Authentication.

Inspect the process description before submitting: it describes the valid input names, types, defaults, and outputs. s2gos-client --help lists commands; s2gos-client execute-process --help lists that command's options.

Prepare a repeatable request

Generate a starting template from the service:

s2gos-client create-request primes_between --format json --config local-client.yaml

Generated values are suggestions, and may need editing before the request is valid for that process. Save your actual request as JSON or YAML. The supplied examples/guides/primes-request.json contains:

{
  "process_id": "primes_between",
  "inputs": {
    "min_val": 10,
    "max_val": 80
  }
}

Keep request files with your analysis so the chosen inputs are recorded. See Execution requests for nested inputs, output settings, and the distinction between CLI request files and Python ProcessRequest objects.

Validate, then submit

s2gos-client validate-request --request examples/guides/primes-request.json

validate-request works offline. It checks the execution-request structure and parses inputs; it does not fetch the process schema, verify storage access, or guarantee scientific validity. Compare inputs with get-process and review service-side validation errors as well.

When the request is ready, submit it once:

s2gos-client execute-process --request examples/guides/primes-request.json --config local-client.yaml

Alternatively, for a small request you can supply inputs directly:

s2gos-client execute-process primes_between -i min_val=10 -i max_val=80 --config local-client.yaml

These are alternative submissions: running both creates two jobs. Repeated -i options set separate inputs. Values such as numbers, true, arrays, and objects are parsed as JSON where possible. Use a request file for complex values to avoid shell quoting problems. A process ID or input supplied on the command line overrides the corresponding value in the file.

Follow the returned job

The submission prints job information, including jobID and status. Copy that ID and replace YOUR_JOB_ID in the remaining commands:

s2gos-client list-jobs --config local-client.yaml
s2gos-client get-job YOUR_JOB_ID --config local-client.yaml

For accepted or running, check the same job later. For failed, read its message before retrying. When status is successful, retrieve the results:

s2gos-client get-job-results YOUR_JOB_ID --config local-client.yaml

Prime-number results are inline values. Scene results may be links to storage; this command displays the result metadata rather than downloading every linked file. Use the results guide to open datasets in Python.

For machine-readable output, add --format json to discovery, submission, job, and result commands. Save the returned jobID in your script. A zero exit code from submission means the API call succeeded; it does not mean the job finished.

Dismiss a selected job

Only when you intend to cancel or discard that job:

s2gos-client dismiss-job YOUR_JOB_ID --config local-client.yaml

Backend dismissal policies vary, and results may become unavailable afterward. Download or open what you need first. Do not dismiss every job in a shared service as part of tutorial cleanup.

Errors in scripts

The CLI normally returns 0 for success, 1 for input or configuration errors, 2 for remote API errors, and 3 for network transport errors. Stop your script when submission fails instead of trying to parse a job ID from an error message. The global --traceback option provides diagnostic details and changes error exit codes to 1:

s2gos-client --traceback list-processes --config local-client.yaml

Consult the generated CLI reference for all commands and options. Regenerate it after upgrading the underlying client implementation.