Write a script with TypeScript
Write a TypeScript script that saves a note in your library and lists the latest ones, using a key that reaches notes and nothing else.
- You'll build Standup, a TypeScript script that saves a note for the day and lists your last five.
- You need your own Marfa instance, with the CLI signed in to it, as the Quickstart leaves you, at
http://localhost:8600. You also need Node.js 22.18 or later. - You'll have a script that runs with a key of its own, which can read and write notes and nothing else.
The CLI's sign-in stays in your keychain, on your computer. A script carries a key instead: a secret that names exactly which types it can read or write. It works from any computer that can reach your instance, such as a server or a scheduled job.
Make a key for the script
Ask the CLI for a key that can write notes:
marfa keys create --label "Standup script" --source standup --type-permission core.note=writemarfa_k1_…
key 01a1f184-1bed-74ae-afc6-32fc15c97ef3 (Standup script); the plaintext is shown once, keep it now
core.note Read and editThe first line is the key. Copy it now: Marfa shows it only once and keeps only a hash of it.
--type-permission core.note=write lets the key read and write notes, the type core.note, and nothing else. --source standup names where the notes it writes come from, so an app can show and filter them by it.
Create the project
Make a folder for the script, and install the TypeScript SDK with TypeScript itself:
mkdir standup && cd standup
npm init -y
npm pkg set type=module
npm install @withmarfa/client
npm install --save-dev typescript @types/nodeNode.js runs a .ts file by removing its types, so the script needs no build step. TypeScript checks the types. Give it a tsconfig.json:
{
"compilerOptions": {
"module": "nodenext",
"target": "esnext",
"types": ["node"],
"strict": true,
"noEmit": true,
"erasableSyntaxOnly": true,
"verbatimModuleSyntax": true
}
}Then tell the script where your instance is and which key to send, in the same terminal:
export MARFA_API_URL=http://localhost:8600
export MARFA_API_KEY=marfa_k1_…Save a note
Create standup.ts. It makes a client for your instance, then saves what you type after the command as a note, titled with today's date and tagged standup:
import { createClient } from "@withmarfa/client";
const { MARFA_API_URL, MARFA_API_KEY } = process.env;
if (!MARFA_API_URL || !MARFA_API_KEY) {
throw new Error("Set MARFA_API_URL and MARFA_API_KEY first.");
}
const marfa = createClient({ baseUrl: MARFA_API_URL, credential: MARFA_API_KEY });
const text = process.argv.slice(2).join(" ");
if (text) {
const today = new Date().toISOString().slice(0, 10);
const { data, error } = await marfa.POST("/items", {
body: {
type: "core.note",
properties: { title: `Standup ${today}`, body: text },
tags: ["standup"],
},
});
if (error) throw new Error(`${error.error.code}: ${error.error.message}`);
console.log(`Saved ${data.item.id}, version ${data.item.version}`);
}Every call returns data when it works and error when Marfa refuses. Check error first: after that, TypeScript knows the shape of data. Branch on error.error.code, which stays the same, rather than the message.
Run it with a line for today:
node standup.ts "Shipped the export fix, reviewing the importer next"Saved 01a1f184-1ca3-7014-a945-ebd0bce70faf, version 1The note is an item, with an ID and a version that rises each time it changes. Run marfa items list --type core.note --tag standup to see it from the CLI.
List your notes
Add a read to the end of standup.ts. It asks for the five newest notes tagged standup:
const { data, error } = await marfa.GET("/items", {
params: { query: { type: "core.note", tags: "standup", limit: 5 } },
});
if (error) throw new Error(`${error.error.code}: ${error.error.message}`);
for (const note of data.data) {
if ("id" in note) console.log(`${note.properties.title}: ${note.properties.body}`);
}The "id" in note check tells TypeScript each entry is an item: a list that asks for metadata answers each item with its metadata instead. Check the types, then run the script with nothing after it, so it only reads:
npx tsc
node standup.tsStandup 2026-11-19: Shipped the export fix, reviewing the importer nextnpx tsc prints nothing when the types are right. Save another line and run it again: the list shows the newest note first.
See what the key can't do
In standup.ts, change type: "core.note" in the write to type: "core.task", and run it:
node standup.ts "Review the importer"Error: type_not_permitted: No access to type "core.task"Marfa refuses the write with 403 type_not_permitted, because the key holds only notes. The refusal's details.grant names the type and the level the request needed. A key reaches only what you gave it, so a script that leaks its key exposes your notes and nothing else.
Change the type back to core.note. To let the script write tasks too, make a new key that names both types: signed in with marfa login, marfa keys update can take access away from a key but never give it more. A source belongs to one live key, so revoke the first key before you reuse standup:
marfa keys revoke 01a1f184-1bed-74ae-afc6-32fc15c97ef3
marfa keys create --label "Standup script" --source standup \
--type-permission core.note=write --type-permission core.task=writePut the new key in MARFA_API_KEY. Manage keys covers expiry, narrowing and revoking a key.