Code Examples and Common Workflows

Working with source code

You can create a build directly from local source files, instead of from a GitHub repository:

signaloid-cli builds create:source \
  --file main.c \
  --lang C \
  --args "--enable-uncertainty"

Visualizing results

If your task produces Ux Strings (distributional values), you can create plots to visualize them:

signaloid-cli plot ux-string \
  --ux-string "90.600000Ux..." \
  --out distributions/

Example workflow

# Single-file build and run
signaloid-cli builds create:source --file test.c --lang C
signaloid-cli tasks create --build-id <id>
signaloid-cli tasks output --task-id <id>

File management

Upload data file:

signaloid-cli files upload --path data/input.csv --from ./local.csv

List files:

signaloid-cli files ls --path data/

Download results:

signaloid-cli files download --path results/output.txt

Mounting Signaloid Cloud Storage

A task can access the files in your Signaloid Cloud Storage when you mount it as a data source of the task. The mount location becomes the start of the paths that your program opens. With the storage mounted at sd0, the program opens the file data/input.csv of your storage as sd0/data/input.csv:

FILE *  fp = fopen("sd0/data/input.csv", "r");

Describe the Data Source

A data source is a JSON object with four fields:

Field	Value
Object	DataSource
ResourceType	SignaloidCloudStorage
ResourceID	signaloid-cloud-storage:/ followed by your UserID, for example signaloid-cloud-storage:/usr_12345661ad6641899387b6458cc9a2e2
Location	The mount location, for example sd0

The signaloid-cli auth whoami command reports your UserID. The following commands store the data source list in a shell variable:

USER_ID=$(signaloid-cli auth whoami | jq -r '.UserID')

DATA_SOURCES=$(jq -n --arg id "signaloid-cloud-storage:/$USER_ID" \
  '[{Object: "DataSource", ResourceType: "SignaloidCloudStorage", ResourceID: $id, Location: "sd0"}]')

Mount the storage for every task of a build

Pass the data source list to builds create:source with --data-sources. Every task that you create from the build mounts the storage, unless the task request sets data sources of its own:

# Upload the input file that the program reads as sd0/data/input.csv
signaloid-cli files upload --path data/input.csv --from ./input.csv

# Build with the storage mounted at sd0
BUILD_ID=$(signaloid-cli builds create:source \
  --file main.c \
  --lang C \
  --data-sources "$DATA_SOURCES" | jq -r '.BuildID')
signaloid-cli builds watch --build-id "$BUILD_ID" --timeout 600

# Run a task and print its output
TASK_ID=$(signaloid-cli tasks create --build-id "$BUILD_ID" | jq -r '.TaskID')
signaloid-cli tasks watch --task-id "$TASK_ID" --timeout 600
signaloid-cli tasks output --task-id "$TASK_ID"

Mount the storage for a single task

To mount the storage for one task, put the data sources in a task request file and pass the file to tasks create with --params-file. The task uses the data sources of the request file instead of the data sources of the build:

jq -n --argjson ds "$DATA_SOURCES" \
  '{Arguments: "", DataSources: $ds}' > datasources.json

TASK_ID=$(signaloid-cli tasks create \
  --build-id "$BUILD_ID" \
  --params-file datasources.json | jq -r '.TaskID')

The --param option sets only Arguments, so use --params-file for data sources.

Note

• Use a relative mount location, such as sd0 or data/inputs. Absolute paths are not allowed for security reasons.
• A task that you run through the CLI or the API mounts only the data sources of its request or of its build. Without data sources, sd0/ does not exist.
• The data sources of a task request replace the data sources of the build. For example, if the build mounts the storage at sd0 and the task request mounts it at mnt, the task has no sd0/ directory.
• To mount a single folder of your storage, add its path to the ResourceID, as in signaloid-cloud-storage:/<UserID>/<path>. The task then has access to that folder only.
• The API accepts a build whose ResourceID names the storage of another user, but a task from that build stops with the error ErrDataSourceNotFound and has no access to the data of that user.
• Files that the task writes under the mount location appear in your Signaloid Cloud Storage after the task completes.
• A build or task request can mount at most five data sources.
• Builds for the C0-microSD, C0-microSD-plus, and C0-SD core classes cannot mount data sources. The API rejects a build request for these core classes that includes data sources.

See Run a Built Application for the same request through the API, and How to Upload Input Files and Read Them from Your Application for mounting the storage in the Signaloid Cloud Developer Platform.

List available Cores

signaloid-cli cores list

Check help anytime

Every command has built-in help:

signaloid-cli --help
signaloid-cli tasks --help
signaloid-cli tasks create --help

Using authentication in scripts

Shell scripts

#!/bin/bash

API_KEY="your-api-key-here"

# Login
signaloid-cli auth login --api-key $API_KEY

# Verify
if signaloid-cli auth whoami &> /dev/null; then
  echo "✓ Authenticated successfully"
else
  echo "✗ Authentication failed"
  exit 1
fi

# Your commands here
signaloid-cli repos list

For production environments, use a secrets manager.

CI/CD integration

GitHub Actions

name: Signaloid Build

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Setup Node.js
        uses: actions/setup-node@v5
        with:
          node-version: '22'

      - name: Install Signaloid CLI
        run: npm install -g @signaloid/signaloid-cli

      - name: Authenticate
        env:
          SIGNALOID_API_KEY: ${{ secrets.SIGNALOID_API_KEY }}
        run: signaloid-cli auth login --api-key $SIGNALOID_API_KEY

      - name: Run build
        run: |
          signaloid-cli builds create:repo --repo-id $REPO_ID

GitLab CI

build:
  script:
    - npm install -g @signaloid/signaloid-cli
    - signaloid-cli auth login --api-key $SIGNALOID_API_KEY
    - signaloid-cli builds create:repo --repo-id $REPO_ID
  variables:
    SIGNALOID_API_KEY: $SIGNALOID_API_KEY

Tips and tricks

Use JSON output with jq

All commands output JSON, making them perfect for scripting:

# Extract specific fields
BUILD_ID=$(signaloid-cli builds create:repo --repo-id $REPO_ID | jq -r '.BuildID')

# Filter and format
signaloid-cli tasks list | jq '.Tasks[] | select(.Status == "Completed")'

Set environment variables

Store your API key in an environment variable:

export SIGNALOID_API_KEY="your-key"

Then authenticate without typing it:

signaloid-cli auth login --api-key $SIGNALOID_API_KEY