Home› Tools› scorpiox-sdk

scorpiox-sdk core

Headless CLI wrapper for non-interactive agent execution. Runs scorpiox sessions programmatically — ideal for CI/CD pipelines, automation scripts, and server-side orchestration without a TUI.

linux-x64 linux-arm64 macos-arm64 windows-x64

⚙️ Flags & Options (22)

Flag Short Description Takes Value
--version -v ScorpioX version to use for the session Yes
--prompt -p Prompt text to send to the agent (the task instruction) Yes
--repo -r Git repository URL to clone and work in Yes
--branch -b Git branch to checkout (default: main) Yes
--help -h Show help and usage information No
--dry-run -n Simulate execution without running the agent Yes
--tui -i Launch in TUI interactive mode instead of headless No
--provider — LLM provider to use (e.g. claude_code, openai) Yes
--cwd — Working directory for the agent session Yes
--agent — Agent name or path to agent configuration Yes
--image — Container image to use for isolated execution Yes
--sx-branch — ScorpioX branch to use (for development/testing) Yes
--pat — Personal access token for private repository authentication Yes
--local — Run using local scorpiox installation instead of containerized No
--print — Print session output to stdout (machine-readable) No
--serve — Start HTTP server mode for API-driven execution Yes
--host-port — Host port mapping when running in container mode Yes
--session-id — Unique session identifier for tracking and log correlation Yes
--port — Port number for serve mode or container port mapping Yes
--net — Docker network to attach the container to Yes
--volume — Additional volume mount for the container (host:container) Yes
--emit-session — Emit session metadata as JSON to stdout on start No

💡 Usage Examples

Basic headless execution with a prompt
$ scorpiox-sdk --prompt "Refactor the auth module to use JWT tokens"
# Runs agent non-interactively, outputs results to stdout
Clone a repo and run a task
$ scorpiox-sdk --repo https://git.example.com/org/my-project.git \
    --branch develop \
    --prompt "Add unit tests for the payment service"
# Clones repo → checks out branch → executes prompt → prints output
Specify provider and version
$ scorpiox-sdk --provider claude_code \
    --version latest \
    --prompt "Fix the failing CI tests in src/utils"
Run in a custom working directory
$ scorpiox-sdk --cwd /home/dev/projects/my-app \
    --prompt "Review all TODO comments and create issues"
# Uses existing local directory as workspace
Dry run — validate config without executing
$ scorpiox-sdk --dry-run true \
    --repo https://git.example.com/org/app.git \
    --prompt "Migrate database schema"
# ✓ Config validated
# ✓ Repo accessible
# ✓ Provider authenticated
# Dry run complete — no changes made
Containerized execution with image and volume mounts
$ scorpiox-sdk --image scorpiox/agent:latest \
    --volume /data/secrets:/secrets:ro \
    --net my-docker-network \
    --port 8080 \
    --prompt "Deploy staging environment"
# Runs inside container with mounted volumes and custom networking
HTTP server mode for API-driven workflows
$ scorpiox-sdk --serve true --port 9090
# SDK server listening on :9090
# POST /run — submit tasks via HTTP
# GET /health — health check endpoint

# Submit a task via curl:
$ curl -X POST http://localhost:9090/run \
    -H "Content-Type: application/json" \
    -d '{"prompt":"Add input validation to the API"}'
Session tracking with emit-session
$ scorpiox-sdk --session-id build-42-task-7 \
    --emit-session \
    --prompt "Generate API documentation"
# {"session_id":"build-42-task-7","status":"started","ts":"2026-05-29T10:00:00Z"}
# ... agent output ...
# {"session_id":"build-42-task-7","status":"completed","ts":"2026-05-29T10:02:15Z"}
CI/CD pipeline integration
# In a GitHub Actions workflow or CI script:
$ scorpiox-sdk --repo "$GITHUB_REPOSITORY_URL" \
    --branch "$GITHUB_HEAD_REF" \
    --pat "$GIT_PAT" \
    --provider claude_code \
    --print \
    --prompt "Review this PR for security issues and add comments"
# Output is machine-readable for further pipeline processing
Use local scorpiox installation
$ scorpiox-sdk --local \
    --cwd . \
    --prompt "Optimize the build configuration"
# Runs with locally installed scorpiox, no container overhead
Launch TUI mode for interactive debugging
$ scorpiox-sdk --tui --cwd /home/dev/project
# Opens interactive TUI — useful for debugging before automating

📦 Source & Build Info

Source File
scorpiox/scorpiox-sdk.c
Lines of Code
2,085
Dependencies
libsxutil