Git for Git. sy for Switchyard.

Use ordinary git for source control. sy talks to the Switchyard HTTP API for collaboration and control-plane operations; it does not replace Git or grant additional repository authority.

Build from source

Install Git and the Go toolchain declared in sy/go.mod (currently Go 1.26.0). Build the repository; no package-manager installation is advertised. Put the resulting executable on your PATH if you want to invoke it outside this directory.

git clone https://github.com/switchyard-labs/sy.git
cd sy
go build -o sy ./cmd/sy
./sy version
./sy --help

Authenticate and choose a host

Use an explicit HTTPS URL for production. Login prompts for username and a password without terminal echo. Register through the browser first: there is no CLI signup command. Sessions are stored per host; logging in again replaces that host’s account. There is one saved account per host, not named multi-account profiles.

sy auth login --host https://switchyard.cx
sy auth status --json
sy config list --json
sy auth switch https://switchyard.cx
sy auth logout

For automation, --password-stdin reads username then password on separate lines. Supply those from your secret manager; do not put a password in command arguments or shell history. Local HTTP development is supported, but use it only in a trusted local environment. --host URL selects an already-configured host for one invocation. Logout removes its local profile and attempts server logout; server logout is best-effort if the host is unavailable.

Config is $XDG_CONFIG_HOME/switchyard/config.json, or ~/.config/switchyard/config.json; SY_CONFIG_DIR overrides the whole directory. New directories use 0700 and config files 0600. Tokens are stored locally, not encrypted, and normal config inspection does not print them. Protect this file. Existing token-only configs remain readable; log in again if the server has expired or revoked your session.

Repository workflow

Copy the Git remote from the repository’s Code menu and use ordinary Git credentials/transport. After configuring sy, read repository state by canonical owner/repo. These read-only examples use the public demo repository.

git clone GIT_REMOTE
cd CHECKOUT_DIRECTORY
sy repo view alice/demo-semantic --json
sy pr list --repo alice/demo-semantic --json
sy repo list --json

sy repo clone owner/repo is a convenience wrapper around Git using a short-lived scoped read credential; it does not store a token in .git/config. repo view, Actions, Pages, releases and Proposals can derive repository context from a checkout. Use explicit canonical identity when names are ambiguous. Work, Attempt and queue lists do not automatically scope to your checkout. Work lists are account-wide, and the current work list --repo flag does not narrow results; do not use it as a scope guarantee.

Work, Attempts, review and Agents

Work is human intent; an Attempt is an existing isolated candidate branch. Inspect IDs before running anything. Commands below create Work or run an Agent only where indicated. ATTEMPT_ID and PR_ID must be replaced with existing IDs.

sy work list --status open --json
sy work create --title "Improve documentation" --kind task
sy attempt list --work WORK_ID --json
sy attempt view ATTEMPT_ID --json
sy attempt run ATTEMPT_ID --json
sy pr checks PR_ID --json
sy pr findings PR_ID --json
sy agent roles --json
sy agent executions --json
sy attention --json

attempt run invokes the implementer Agent and can publish on its permitted isolated branch. Agent availability depends on the configured worker/provider. agent commands inspect roles/executions; they do not configure all models or start arbitrary roles. The typed CLI does not create Attempts or PRs, run reviews/resolvers, or enqueue a PR: use the browser or documented API for those operations. Permissions and integration policy apply equally to CLI requests.

Optional Proposal workflow

Proposals can be discussed, accepted, deferred, rejected or completed without creating Work. VERSION is the current Proposal version from view; GRAPH_VERSION is the relationship graph version from links. Use a unique operation ID for linked Work, reusing it only for retries with identical input. These examples after list/view mutate state.

sy proposal list --repo owner/repo --json
sy proposal view PROPOSAL_ID --repo owner/repo --json
sy proposal create --repo owner/repo --title "Discuss the API" --body "Evidence and alternatives"
sy proposal update PROPOSAL_ID --repo owner/repo --version VERSION --description "Revised evidence"
sy proposal comment PROPOSAL_ID --repo owner/repo --version VERSION --body "A possible approach"
sy proposal links PROPOSAL_ID --repo owner/repo --json
sy proposal link PROPOSAL_ID WORK_ID --repo owner/repo --version GRAPH_VERSION --target-kind work --relation work
sy proposal accept PROPOSAL_ID --repo owner/repo --version VERSION --reason "Agreed"
sy proposal work PROPOSAL_ID --repo owner/repo --version VERSION --operation-id proposal-work-example-001

generate asks the proposer Agent; --provider, --model and --credential override that request. The credential argument is an ID, never a secret. --execution-id recovers a completed generation instead of starting another. Check sy proposal generate --help for all options.

Integration Queue and Needs Attention

Inspect queue and attention state from the terminal. Requeue is a mutation, not policy bypass. Legacy/unpinned items or changed source identities require a fresh source-bound enqueue decision; requeue must not be treated as a repair for every blocked item.

sy queue list --status blocked --json
sy queue view QUEUE_ID --json
sy attention view TARGET_ID --json
sy queue requeue QUEUE_ID

Durable workflows

Inspect definitions and runs. Running a workflow can invoke Agents and change repository state under its configured role/policy; it is not a read-only status check.

sy workflow list --json
sy workflow view WORKFLOW_ID --json
sy workflow runs --json
sy workflow run WORKFLOW_ID --repo owner/repo --branch attempt-branch

Actions: inspect, run and capture logs

List/view/logs are reads. Manual run, rerun and cancel mutate state. EXACT_SHA is a full 40-hex commit SHA; the selected ref must be allowed by the approved Action definition. A rerun uses the original exact source.

sy actions list --repo owner/repo --json
sy actions view RUN_ID --repo owner/repo --json
sy actions logs RUN_ID --repo owner/repo --follow
sy actions run --repo owner/repo --sha EXACT_SHA --ref refs/heads/main
sy actions rerun RUN_ID --repo owner/repo --failed
sy actions cancel RUN_ID --repo owner/repo

Logs are bounded captured step output. Following ends at terminal completion; Ctrl-C stops the follower, not the Action. logs --json emits newline-delimited JSON events.

Pages: configure, build, then promote

The actual listing command is deployments, not list. Project sites are the default; add --kind owner for an owner site with an explicit backing repository. Read VERSION from status and GENERATION from deployments before mutations. Operation IDs identify identical explicit retries.

sy pages status --repo owner/repo --json
sy pages deployments --repo owner/repo --json
sy pages view DEPLOYMENT_ID --repo owner/repo --json
sy pages configure --repo owner/repo --version VERSION --ref main --directory . --build "nift build" --output public
sy pages deploy --repo owner/repo --version VERSION --operation-id pages-build-example-001
sy pages promote DEPLOYMENT_ID --repo owner/repo --generation GENERATION --operation-id pages-promote-example-001

Initial configuration leaves --version empty; updates require the current version. Private-source public output requires --acknowledge-public. A build does not automatically promote production. rollback selects a retained deployment using the same generation/operation-ID guards. Project assets and routing must respect their site base path.

Releases and source archives

Create a draft from an existing Git tag. The release records its resolved full commit SHA; publication verifies the tag still points there and freezes assets. Upload/download use bounded transfers; downloads verify metadata size and SHA256 and never overwrite an existing path.

sy release list --repo owner/repo --json
sy release view v0.1.0 --repo owner/repo --json
sy release create v0.1.0 --repo owner/repo --title "First preview" --notes-file notes.md
sy release upload v0.1.0 package.zip --repo owner/repo
sy release publish v0.1.0 --repo owner/repo
sy release download v0.1.0 package.zip --repo owner/repo --output downloaded-package.zip
sy repo archive owner/repo --ref main --format zip --output source.zip

The CLI archive command first resolves the requested ref, verifies the server commit header and downloads that SHA. Generic HTTP branch/tag archive URLs resolve when requested. Submodule contents and gitattributes export rules are not supported. Release create/upload/publish are mutations; downloads and archives write local files only.

Organisations and operator inspection

Organisation commands inspect membership-visible organisations; they do not manage teams or invitations. Status reports host, authenticated user and best-effort checkout identity, not service health or a queue dashboard. Host operators still use their normal service tools.

sy org list --json
sy org view ORG_ID --json
sy status --json

Raw API escape hatch

Use typed commands for common operations; use api for lower-level access. It returns the server body rather than a typed CLI envelope. Method defaults to GET; --method and --body are available for mutations, subject to the same server permissions.

sy api /api/repositories --json
sy api GET /api/repositories/alice/demo-semantic

The hardened PR enqueue API requires the caller-viewed source_sha. There is no typed enqueue command. Read the current API contract before constructing that mutation; do not assume a branch name alone identifies the checked source.

Machine-readable output and exit behavior

Most typed operations emit JSON with --json. List commands commonly return an items array; views return domain objects or command-specific envelopes. Inspect each shape rather than assuming all views share a schema. Logs are NDJSON. Errors go to stderr and a nonzero exit means failure.

sy repo list --json
sy queue list --status blocked --json

Exceptions in the current implementation: version --json still prints human text; config get --json and config set-host --json emit no result; auth switch/logout still print text, and browse opens the browser without a JSON result. These are not uniform machine interfaces. Use config list --json and auth status --json for machine inspection.

Code 2 is declared for invalid input but the current error mapper does not return it. Raw api does not share the typed HTTP-status taxonomy. Do not branch on a promised invalid-input code or treat every nonzero result as authentication failure.

Verified command inventory

Audited from the command tree/help and implementation. All network commands require a configured host; protected reads and platform mutations require a valid session plus server permission. Public repository reads may work with a token-free configured profile. Local profile commands do not authenticate merely to switch hosts. Help and version do not need a host.

Run sy COMMAND --help for exact flags. The sy repository contains implementation and tests; the audit inventory records the verified surface and known drift.