Command-line guide

Use cuiman to discover processes, submit jobs, and retrieve their results. The commands below are maintained in cli.sh. Copy individual recipes into Bash or PowerShell. Running the entire file as a script exits immediately without executing the recipes.

Start and configure

In a development checkout, run pixi install, then start the test service in a separate terminal:

pixi run serve

In a second terminal, run pixi shell from the repository root and configure Cuiman for this unauthenticated local service:

cuiman configure --api-url http://127.0.0.1:8008 --auth-type none

This updates the saved Cuiman profile. For a remote deployment, use its URL and authentication settings, then cuiman login when interactive sign-in is needed. See Configuration and Authentication.

Inspect a process

cuiman --help
cuiman list-processes
cuiman get-process primes_between

The local service provides primes_between, with integer inputs min_val and max_val. Inspect the actual process description when using another service. Add --help after any command for its arguments and options.

Prepare and validate inputs

Print a request template:

cuiman create-request primes_between --format json

To use a file, copy the JSON into a UTF-8 file named request.json, edit its inputs, then pass --request request.json to validation or submission. Explicit UTF-8 saving also avoids Windows PowerShell 5.1's UTF-16 redirection default. Generated defaults are only a starting point.

For this small request, supply inputs directly:

cuiman validate-request primes_between -i min_val=10 -i max_val=80

Validation checks the request structure locally. It does not contact the service or validate all process-specific constraints.

Submit a job

cuiman execute-process primes_between -i min_val=10 -i max_val=80

Save the jobID printed by the server. Replace YOUR_JOB_ID below with that value. Submission starts a new job each time; it does not wait for completion.

Monitor and retrieve results

cuiman list-jobs
cuiman get-job YOUR_JOB_ID

Repeat get-job while the status is accepted or running. Once it is successful, retrieve the results:

cuiman get-job-results YOUR_JOB_ID

The prime-number result contains the primes from 11 through 79. For an example that deliberately fails, submit:

cuiman execute-process sleep_a_while -i duration=2 -i fail=true

Inspect this new job using its own returned ID. Its failed status and message explain why successful results are unavailable.

Use a JSON request for a dataset

The result opener guide provides a small scene request. It writes guide-scene.zarr relative to the server's working directory, replacing any existing dataset at that path. Choose an unused output_path before submitting. Validate and then submit it:

cuiman validate-request simulate_scene --request examples/guides/cuiman/simulate-scene-request.json

cuiman execute-process simulate_scene --request examples/guides/cuiman/simulate-scene-request.json

Retain this job's returned ID. Its result links to the dataset; use the Python opener example to read it.

Cancel or delete a selected job

This cancels a running job or deletes a finished job:

cuiman dismiss-job YOUR_JOB_ID

Open the App

cuiman show-app

Keep the terminal running; press Ctrl+C to stop the App server. See the App guide for the visual workflow and the CLI Reference for the complete command list.

The original CLI notebook remains available as a historical example; use the commands above with the current client.