yeet global

O yeet

The yeet object is the primary host-provided API surface, installed as a global before script evaluation begins.

P yeet.args

yeet.args: Record<string, string | boolean | (string | boolean)[]> & { _: string[] }

A parsed, read-only object containing CLI arguments passed when the script was run. Parsing follows minimist conventions:

Input	Result
--foo bar	{ foo: "bar" }
--foo=bar	{ foo: "bar" }
--foo	{ foo: true }
--no-foo	{ foo: false }
--multi-word-flag	{ multi_word_flag: true } — kebab-case is converted to snake_case
-f bar	{ f: "bar" }
-abc	{ a: true, b: true, c: true }
bare-word	appended to _: [...]
--	halts flag parsing; remaining words go to _
Duplicate flags	coalesce into arrays

// yeet run script.js --verbose --tag alpha --count 3 file.txt
console.log(yeet.args);
// { verbose: true, tag: "alpha", count: "3", _: ["file.txt"] }

note

All values are strings or booleans. Numeric strings are not coerced to numbers automatically.

---

F yeet.exit

exit(): void

Terminates the running isolate. Any registered exit handlers run first.

yeet.exit();

---

O yeet.graph

Interface to the yeet system graph — a structured data query layer backed by GraphQL.

F yeet.graph.query

query(gql: string): Promise<{ data?: any; errors?: { message: string }[] }>

Executes a one-shot GraphQL query. Rejects with { code, message } only on transport-level failures.

const { data, errors } = await yeet.graph.query(
  `{ host { uptime { uptime } } }`
);
if (errors) throw new Error(errors[0].message);
console.log(data.host.uptime.uptime);

A successful response looks like:

{
  "data": { "host": { "uptime": { "uptime": 12345 } } }
}

On a GraphQL error:

{
  "data": null,
  "errors": [{ "message": "field 'foo' not found" }]
}

To explore what the graph exposes, run yeet graph dump for the full SDL or yeet graph query '<gql>' for ad-hoc queries from the shell.

F yeet.graph.subscribe

subscribe(gql: string, callback: (data: any) => void): string

Starts a live subscription to a GraphQL query. The callback fires each time new data arrives. Returns a ticket string — capture it if you intend to unsubscribe later.

const ticket = yeet.graph.subscribe(
  `subscription {
    network_interface_stats(interval_ms: 1000) {
      name recv_bytes sent_bytes
    }
  }`,
  (data) => console.log(data)
);

F yeet.graph.unsubscribe

unsubscribe(ticket: string): Promise<boolean>

Cancels a running subscription. Returns true if found and removed, false otherwise.

await yeet.graph.unsubscribe(ticket);

---

M yeet.alert

alert(...args: any[]): Promise<any>

Dispatches an alert event to the yeet platform and returns a Promise that settles when the platform responds.

Parameter	Type	Description
...args	any[]	Any JSON-serializable values, forwarded to the platform as-is.

Returns a Promise that resolves or rejects with the JSON payload returned by the platform.

Currently, yeet.alert supports sending Slack messages. Sending a Slack alert requires connecting your Slack workspace — set up the OAuth integration at yeet.cx/settings before use.

Pass an object with method: "slack", a channel, and a text fallback. You can also include a blocks array for richer formatting using Slack Block Kit.

const result = await yeet.alert({
  method: "slack",
  channel: "#alerts",
  text: "Container down",
  blocks: [
    {
      type: "header",
      text: { type: "plain_text", text: "Container down" },
    },
    {
      type: "section",
      fields: [
        { type: "mrkdwn", text: "*Container:*\nnginx" },
        { type: "mrkdwn", text: "*Status:*\nexited" },
      ],
    },
  ],
});
console.log("alert sent", result);

Promise lifecycle

The platform responds with an HTTP status that determines how the promise settles:

Status	Outcome
200 OK	Resolves immediately with the response payload.
202 Accepted	Parked — the platform will settle it later out-of-band.
429 Too Many Requests	Rejects with RateLimited. Not retried.
Other 4xx / 5xx	Rejects with the response payload (up to 3 retries on auth and server errors).

Failure modes

The promise rejects if:

• No access token is available (not logged in).
• All retry attempts are exhausted on a server or auth error.
• The platform returns 429 (rate limited).
• The platform returns a non-success status after retries.

---

F yeet.caps

caps(): Promise<{
  credentials: {
    oauth_id: string;
    provider: string;
    provider_account_id: string;
    scope: string;
    token_type: string;
  }[];
}>

Returns the capabilities available to the running script. Currently this includes OAuth credentials connected to your yeet installation — additional capability types will be exposed here as the platform grows.

const { credentials } = await yeet.caps();
console.log(credentials);
// [
//   {
//     oauth_id: 'OAUTH-01JXXXXXXXXXXXXXXXXXXXXXXXXX',
//     provider: 'linear',
//     provider_account_id: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
//     scope: 'read write',
//     token_type: 'Bearer'
//   }
// ]

Field	Type	Description
oauth_id	string	Unique identifier for this credential within yeet.
provider	string	The OAuth provider name (e.g. "linear", "slack").
provider_account_id	string	The account ID as assigned by the provider.
scope	string	Space-separated list of scopes granted by the token.
token_type	string	Token type returned by the provider (typically "Bearer").

OAuth integrations are configured at yeet.cx/settings. If no credentials have been connected, credentials will be an empty array.

---

F yeet.whoami

whoami(): Promise<{ owner_id: string; host_id: string } | null>

Resolves with the daemon's identity — the account that owns this host and the host's id on the platform — or null while the daemon is not signed in. It is the same answer yeet whoami gives on the command line. The access and refresh tokens stay in the daemon; nothing secret crosses into the isolate.

The promise rejects only if the daemon is tearing down its identity store, so a script can branch on signed-out without a try/catch:

const me = await yeet.whoami();

if (me === null) {
  console.log('This host is not signed in. Run `yeet login`, or see yeet:auth.');
  yeet.exit();
}

console.log(`Signed in as ${me.owner_id} on host ${me.host_id}`);

To sign the daemon in from a script rather than just check, use login() from yeet:auth; it resolves with this same shape.

---

F yeet.test

test(fn: TestFn): void
test(name: string, fn: TestFn): void
test(name: string, options: TestOptions, fn: TestFn): void
test(options: TestOptions, fn: TestFn): void
test(definition: TestOptions & { name: string; fn: TestFn }): void

type TestFn = (t: TestContext) => void | Promise<void>;

interface TestOptions {
  name?: string;
  ignore?: boolean;
  only?: boolean;
  timeout?: number; // milliseconds, 5000 by default
}

Registers a test case. Without a name, the case takes fn.name. The cases run only under yeet test; under yeet run and in a service, yeet.test registers nothing, so a script can carry its own tests. Writing tests walks through an example, and yeet:assert has the assertions to use in a case.

F yeet.test.only

only(name: string, fn: TestFn): void

Registers a case with only set. It takes the same arguments as yeet.test. If any case has only, only those cases run, and the run fails anyway.

F yeet.test.ignore

ignore(name: string, fn: TestFn): void

Registers a case with ignore set. It takes the same arguments as yeet.test. The case is reported as ignored and does not run.

F yeet.test.beforeAll, beforeEach, afterEach, afterAll

beforeAll(fn: () => void | Promise<void>): void
beforeEach(fn: () => void | Promise<void>): void
afterEach(fn: () => void | Promise<void>): void
afterAll(fn: () => void | Promise<void>): void

Registers a hook. The after hooks run in reverse order.

O TestContext

The t that a case or a step receives.

M t.step

step(name: string, fn: TestFn): Promise<boolean>

Runs a nested step. It takes the same arguments as yeet.test. It resolves to false if the step failed or was ignored, and a failed step fails its case.