@kody/raycast

@kody/raycast

Official Raycast mark (brand red #FF6363) from the Raycast press kit. Raycast® is a trademark of Raycast Technologies Ltd. This package is not affiliated with or endorsed by Raycast.

Share this listing as https://kody.codes/@kody/raycast — never a /community/{listing_id} URL.

Intent

Give every Kody account a small, generic HTTP front door that Raycast (or curl, Shortcuts, Alfred, and other clients) can call to list saved packages, load export metadata, and invoke another owned package. Success means a forked copy browses that account's packages with a token minted for this raycast package — no Kent-only package lists and no personal tokens baked into source.

Live @kody/raycast lists official kody-scope packages. Fork or install first for a personal launcher.

Agent setup

Do not ask anyone to paste tokens into chat. Hand them the prefilled URL, wait until they confirm the token exists in Raycast (or another local store), then call the invocation route.

This package does not use account secrets. Auth is a package invocation token created in the browser.

1. Fork or install this listing when the client should see the user's packages. Invoking the live @kody/raycast copy lists official packages.
2. Open the token form for this package (exportNames=*):

https://kody.codes/account/packages/ea5db329-3cc0-4daa-b23a-3954cccfe560?newToken=1&name=Raycast&exportNames=*

After a fork, replace the package id with the saved id of their raycast copy (or call kody:@kody/raycast/guide). Do not put the raw token in the URL. Generate or paste it in the form.

3. Call the owner-scoped invocation route:

POST https://kody.codes/@YOUR_USERNAME/api/package-invocations/raycast/<export>
Authorization: Bearer <token>
Content-Type: application/json

{"params":{},"source":"raycast","idempotencyKey":"raycast:raycast:list-packages:<uuid>"}

To run another owned package, call invoke on this package. The bearer stays scoped to raycast; packages.invoke enters the target runtime.

There is no /account/secrets/new step for this package.

Exports

• kody:@kody/raycast — describe the package and safety metadata
• kody:@kody/raycast/guide — prefilled token URL and invocation shape
• kody:@kody/raycast/list-packages — list saved packages
• kody:@kody/raycast/get-package — load one package's export metadata
• kody:@kody/raycast/invoke — run another owned package; supports dryRun

This package declares no jobs.

dryRun

./invoke is the mutation. Pass dryRun: true to resolve the target and return a preview without calling it. Live invokes are opt-in (this is a launcher). Forward params.dryRun when the target package also supports dry-run.

import invoke from 'kody:@kody/raycast/invoke'

const preview = await invoke({
	kodyId: 'notify',
	exportName: '.',
	params: { dryRun: true },
	dryRun: true,
})

In-package smoke

import describe from 'kody:@kody/raycast'
import listPackages from 'kody:@kody/raycast/list-packages'
import getPackage from 'kody:@kody/raycast/get-package'
import invoke from 'kody:@kody/raycast/invoke'

const info = await describe()
const { packages } = await listPackages()
const pkg = await getPackage({ kodyId: packages[0]?.kodyId })
const preview = await invoke({
	kodyId: pkg.kodyId,
	exportName: pkg.exports[0]?.exportName || '.',
	params: {},
	dryRun: true,
})

Raycast / external client example

Minimal fetch helper for a Script Command, a tiny extension, or any local tool. Every HTTP call hits this raycast package:

async function invokeRaycastExport(
	username: string,
	exportName: string,
	token: string,
	params: Record<string, unknown> = {},
) {
	const path = exportName.split('/').filter(Boolean).map(encodeURIComponent).join('/')
	const response = await fetch(
		`https://kody.codes/@${encodeURIComponent(username)}/api/package-invocations/raycast/${path}`,
		{
			method: 'POST',
			headers: {
				authorization: `Bearer ${token}`,
				'content-type': 'application/json',
			},
			body: JSON.stringify({
				params,
				source: 'raycast',
				idempotencyKey: `raycast:raycast:${exportName || 'root'}:${crypto.randomUUID()}`,
			}),
		},
	)
	const body = await response.json()
	if (!response.ok) {
		throw new Error(`Kody invocation failed (${response.status}): ${JSON.stringify(body)}`)
	}
	return body.result ?? body.data ?? body.output ?? body
}

const { packages } = await invokeRaycastExport(
	'YOUR_USERNAME',
	'list-packages',
	process.env.KODY_TOKEN!,
)

curl

curl -sS -X POST \
  "https://kody.codes/@YOUR_USERNAME/api/package-invocations/raycast/list-packages" \
  -H "Authorization: Bearer $KODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"params":{},"source":"raycast","idempotencyKey":"raycast:raycast:list-packages:1"}'

Building a Raycast extension (optional)

You do not need a Store extension — Script Commands or the snippet above are enough. For a picker/launcher:

1. Preferences: Kody base URL, username, and invocation token.
2. Add command: list-packages, then get-package, then save { kodyId, exportName, params } locally.
3. Run: POST /@:username/api/package-invocations/raycast/invoke with { kodyId, exportName, params } and source: "raycast". Preview risky targets with dryRun: true first.
4. Keep personal automations in the user's packages. This package is the HTTP front door.