---
sidebar_position: 2
title: yeet global
---

# yeet global

## <Obj /> yeet {#yeet}

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

## <Property /> yeet.args {#yeet-args}

```ts
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 |

```js
// 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.
:::

---

## <Fn /> yeet.exit {#yeet-exit}

```ts
exit(): void
```

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

```js
yeet.exit();
```

---

## <Obj /> yeet.graph {#yeet-graph}

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

### <Fn /> yeet.graph.query {#yeet-graph-query}

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

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

```js
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:

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

On a GraphQL error:

```json
{
  "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.

### <Fn /> yeet.graph.subscribe {#yeet-graph-subscribe}

```ts
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.

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

### <Fn /> yeet.graph.unsubscribe {#yeet-graph-unsubscribe}

```ts
unsubscribe(ticket: string): Promise<boolean>
```

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

```js
await yeet.graph.unsubscribe(ticket);
```

---

## <Method /> yeet.alert {#yeet-alert}

```ts
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](https://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](https://api.slack.com/block-kit).

```js
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.

---

## <Fn /> yeet.caps {#yeet-caps}

```ts
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.

```js
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](https://yeet.cx/settings). If no credentials have been connected, `credentials` will be an empty array.

---

## <Fn /> yeet.whoami {#yeet-whoami}

```ts
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`:

```js
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()`](./yeet-auth#login) from [`yeet:auth`](./yeet-auth); it resolves with this same shape.