swytchcode

README

swytchcode Go runtime

Thin runtime wrapper around the Swytchcode CLI. Calls swytchcode exec for you so you can stay in Go without shell boilerplate.

Requires: The swytchcode CLI must be installed. The binary is located automatically — no configuration needed in most environments. Resolution order:

1. SWYTCHCODE_BIN env var — explicit override.
2. $PATH lookup via exec.LookPath — the standard system resolution.
3. Common install paths — ~/.local/bin, /usr/local/bin (Unix) or %LOCALAPPDATA%\Programs\swytchcode\bin (Windows).

Install

go get gitlab.com/swytchcode/go-runtime

Use

JSON mode (default)

package main

import (
	"context"
	"fmt"
	swytchcode "gitlab.com/swytchcode/go-runtime"
)

func main() {
	result, err := swytchcode.Exec(context.Background(), "api.account.create", map[string]string{
		"email": "test@example.com",
	}, nil)
	if err != nil {
		panic(err)
	}
	fmt.Println(result)
}

Equivalent to: swytchcode exec api.account.create --json with args on stdin.

Request input (args): The third argument to Exec is the kernel args object (sent as JSON on stdin). Use this shape so the kernel builds the request correctly:

• body — Request body (object).
• params — Query/path params (e.g. map[string]string{"id": "cluster-123"}).
• Authorization — Auth header value (e.g. "Bearer token123").
• headers — Additional request headers (map of header name to value).
• Other top-level keys are passed as query params.

Example with body, params, and headers:

swytchcode.Exec(ctx, "api.cluster.get", map[string]any{
	"params":         map[string]string{"id": "cluster-123"},
	"Authorization": "Bearer token123",
	"headers":       map[string]string{"X-Request-Id": "abc-123"},
}, nil)

Raw mode

Get stdout as bytes instead of parsing JSON:

	result, err := swytchcode.Exec(ctx, "api.report.export", map[string]string{"id": "123"}, &swytchcode.ExecOptions{Raw: true})
	// result is []byte

Options

• Cwd – Working directory for the process (default: current directory).
• Env – Extra environment variables (merged with the current process env).
• Raw – If true, use --raw and return stdout as []byte.
• DryRun – If true, pass --dry-run to the CLI; request details (method, url, headers, body) are output instead of calling the server.
• AllowRaw – If true, pass --allow-raw to the CLI; required for executing raw methods (kernel has this disabled by default).

This runtime invokes swytchcode exec [canonical_id] with the flags above. For full exec behavior, see the Swytchcode kernel documentation.

Environment variables

Variable	Description
SWYTCHCODE_BIN	Override the resolved binary path. Set this only when automatic resolution does not find the correct binary (e.g. non-standard install locations or containerised environments).
SWYTCHCODE_TOKEN	Auth token passed to the CLI via the process environment.

Error handling

Failures return a *SwytchcodeError (spawn error, non-zero exit, invalid JSON). Use the helper to narrow:

	result, err := swytchcode.Exec(ctx, "api.account.create", input, nil)
	if err != nil {
		if swytchcode.IsSwytchcodeError(err) {
			fmt.Println(err.(*swytchcode.SwytchcodeError).Message, err.(*swytchcode.SwytchcodeError).Cause)
		}
		return err
	}

What this library is

• A thin process wrapper over the Swytchcode shell.
• A stable call surface: Exec(ctx, canonicalID, input, opts).
• A convenience for developers and IDE agents.

What this library is not

• An HTTP SDK or API client.
• A replacement for the shell. All authority stays in the Swytchcode CLI.

This library must not and does not:

• Read .swytchcode/* or parse tooling.json.
• Validate schemas or add retries/timeouts.
• Call the registry or embed auth logic.

It is a pipe, not a brain.

For Cursor / Claude / Other agents

Generate code that uses this runtime instead of subprocess boilerplate.

Preferred:

import swytchcode "gitlab.com/swytchcode/go-runtime"

func createAccount(ctx context.Context, input map[string]string) (any, error) {
	return swytchcode.Exec(ctx, "api.account.create", input, nil)
}

Avoid: os/exec boilerplate, HTTP calls, or config parsing. Use Exec(...) and let the CLI handle execution and policy.

Documentation

Index

• func Exec(ctx context.Context, canonicalID string, input any, opts *ExecOptions) (any, error)
• func IsSwytchcodeError(err error) bool
• type ExecOptions
• type SwytchcodeError
  • func (e *SwytchcodeError) Error() string

Functions

func Exec

func Exec(ctx context.Context, canonicalID string, input any, opts *ExecOptions) (any, error)

Exec runs swytchcode exec <canonicalID> with optional JSON args on stdin. It returns parsed JSON as an interface{} (default) or raw stdout as []byte when opts.Raw is true. The swytchcode binary must be on PATH.

The input argument is the kernel args object sent on stdin. Use this shape so the kernel builds the request correctly: body (request body), params (query/path params), Authorization (auth header value), headers (map of header name to value); other top-level keys are passed as query params. See the Swytchcode kernel documentation.

func IsSwytchcodeError

func IsSwytchcodeError(err error) bool

IsSwytchcodeError reports whether err is a *SwytchcodeError.

Types

type ExecOptions

type ExecOptions struct {
	// Cwd is the working directory for the swytchcode process. If empty, the current process directory is used.
	Cwd string
	// Env is merged with the current process environment. Keys and values are added or override.
	Env map[string]string
	// Raw, if true, passes --raw to the CLI and returns stdout as []byte instead of parsing JSON.
	Raw bool
	// DryRun, if true, passes --dry-run to the CLI; request details are output instead of calling the server.
	DryRun bool
	// AllowRaw, if true, passes --allow-raw to the CLI; required for executing raw methods (disabled by default in kernel).
	AllowRaw bool
}

ExecOptions configures an exec call.

type SwytchcodeError

type SwytchcodeError struct {
	Message string
	Cause   any
}

SwytchcodeError is returned when exec fails: spawn error, non-zero exit, or invalid JSON output.

func (*SwytchcodeError) Error

func (e *SwytchcodeError) Error() string