slingdata-io/sling-cli/sling-platform

Sling Platform — Working with Hosted Projects

The Sling Platform stores replications, pipelines, jobs, and connections on a server. The CLI authenticates via SLING_PROJECT_TOKEN and exposes the platform through sling platform ... subcommands. Full reference: https://docs.slingdata.io/llms.txt.

Authentication

Every platform command requires SLING_PROJECT_TOKEN. Project tokens are created in the platform UI (Settings → Tokens). Sling never reads the token from an AI agent's environment — only its own.

export SLING_PROJECT_TOKEN=...   # required
sling platform status             # smoke test: project info + counts

Subcommand map

Most list/get commands accept -o json — prefer it when parsing output.

Two MCP servers

If both the CLI stdio MCP (sling serve mcp) and the Platform HTTP MCP are attached, pick by location:

• Local env.yaml, local files, local validate → stdio tools connection, database, file_system, replication, pipeline, api_spec.
• Hosted project (this skill) → platform tools jobs, executions, files, connections, agents, replications, pipelines, builds, project, monitors, specs.

Same vocabulary as the CLI. jobs trigger in the shell is jobs.trigger over MCP.

Job payload shape

jobs save sends the JSON straight to the platform's Job model. Key fields:

{
  "name": "Users daily",
  "type": "replication",
  "file_name": "replications/users.yaml",
  "active": true,
  "schedules": ["0 4 * * *"],
  "timezone": "America/New_York",
  "streams": [],
  "config": {"mode": "incremental", "threads": 2, "retries": 1}
}

• Omit `id` to create — the server assigns a job_... ID. Include the existing id to update.
• type: replication | pipeline | query | monitor.
• schedules is an array of cron expressions (multiple allowed), paired with timezone. active controls whether they fire.
• streams: [] means all streams; list names to restrict.
• config (optional): mode, threads, retries, timeout, range, variables (list of {NAME: value} maps — set SLING_AGENT_ID to pin an agent).
• Free-plan projects cannot save active: true, threads > 1, or retries — the server rejects with an upgrade message; monitors need the Advanced plan.

Common workflows

Create + schedule a job

cat job.json | sling platform jobs save -f -    # no "id" → creates
sling platform jobs get <returned_id>
sling platform jobs trigger <returned_id> --wait   # verify it runs

Activate / deactivate a job

sling platform jobs deactivate <id>   # pause: schedules stop firing
sling platform jobs activate <id>     # resume

For any other field change, note `jobs save` is a full replace, not a patch — sending only {"id": ..., "name": "new"} would wipe the job's schedules, streams, and config (the CLI warns and lists the fields that would be cleared). Always round-trip the full object:

sling platform jobs get <id> > job.json
# edit job.json
cat job.json | sling platform jobs save -f -

Check history / last run

sling platform jobs status --name users        # per-job: status, last executed, next scheduled
sling platform executions list --job-name users --limit 1     # most recent run (name must match one job)
sling platform executions list --job-id <id> --since 7d       # last week's history
sling platform executions list --status error --since 24h     # all recent failures

Investigate a failed exec

sling assist --id <exec_id> starts an assist session with this workflow pre-loaded when the exec exists on the platform.

1. sling platform executions list --status error --limit 5 — find the failure.
2. sling platform executions status <exec_id> — which task/stream/step failed.
3. sling platform executions log <exec_id> --status error — logs for failing tasks only (add --task <name> to zoom in; --no-color for clean text).
4. sling platform files get <file_name> — pull the YAML to read/edit locally.
5. Validate the fix locally with MCP replication validate / pipeline validate, then run it: sling run -r users.yaml or sling run -p pipeline.yaml.
6. cat fixed.yaml | sling platform files save <file_name> -f - — push back.
7. sling platform jobs trigger <job_id> --wait — verify green.

Edit a platform file in place

sling platform files get replications/users.yaml > users.yaml
# edit locally, validate via MCP, then sling run -r users.yaml
cat users.yaml | sling platform files save replications/users.yaml -f -

For bulk work, sling init + sling platform sync keeps a local directory mirrored with the platform instead of per-file get/save.

Monitors

Monitors observe data without moving it: schema drift, freshness, row counts, column statistics, and anomaly detection. They are YAML files (connection: + objects:) saved under the project's monitors/ directory and scheduled as jobs with type: monitor. They require the Advanced plan.

To author a monitor, read MONITORS.md — object and column keys, patterns, anomalies, and a worked example.

Agents & Self-Hosting (docs index)

Jobs execute on agents in the customer's infrastructure — data never flows through the control plane. For deployment questions, fetch:

• Agents (deploy, pin via SLING_AGENT_ID): https://docs.slingdata.io/sling-platform/agents.md
• Self-hosting the platform: https://docs.slingdata.io/sling-platform/self-hosting.md
• Architecture: https://docs.slingdata.io/sling-platform/architecture.md
• Platform HTTP API: https://docs.slingdata.io/sling-platform/api.md

Tips

• The platform never executes against the user's local env.yaml — connections are project-scoped. "connection not found" means missing on the platform, not locally.
• files get returns the file with ${VAR} references preserved — do not interpolate them.
• When unsure of job field names, jobs get a known-good job and edit that JSON rather than composing from scratch.
• jobs trigger --streams a,b and --full-refresh override the job's saved streams/mode for that one run only.