Puter

Rename a file or directory in Puter in place, keeping it in the same parent directory. To move an item to a different directory use fs_move instead. Equivalent to PuterJS puter.fs.rename(path, new_name).

Begin an out-of-band file upload and get back a presigned URL to PUT the bytes to. PREFER THIS OVER fs_write_file for any file you already have on disk, and for anything large or binary: the bytes go straight from your machine to storage instead of being base64-encoded through this conversation. Three steps: (1) call this with the destination path and the file's exact byte size, (2) run the returned `upload_command` in a shell, (3) call fs_complete_upload with the returned upload_id — the file does not exist in Puter until you do. Get the exact size with `wc -c < file` and pass it verbatim; a …

Get metadata (name, size, type, timestamps, uid) for a file or directory in Puter. Equivalent to PuterJS puter.fs.stat(path).

Write (create or overwrite) a file in Puter from content you supply inline. Provide content as UTF-8 text, or set encoding="base64" to write binary data. Best for text you are generating anyway; for a file that already exists on disk — especially a large or binary one — use fs_start_upload instead, which moves the bytes out of band. Equivalent to PuterJS puter.fs.write(path, data).

Publish a new static website by creating a hosting subdomain. The site goes live at https://<subdomain>.puter.site. Point it at a Puter directory (root_dir) to serve that directory's files (e.g. an index.html) as a website; omit root_dir to reserve the subdomain and attach a directory later with hosting_update. Typical flow: fs_mkdir a directory, fs_write_file your index.html into it, then hosting_create with that root_dir. Equivalent to PuterJS puter.hosting.create(subdomain, root_dir).

Unpublish a website by deleting its hosting subdomain. This takes https://<subdomain>.puter.site offline but does NOT delete the underlying Puter directory or its files. Equivalent to PuterJS puter.hosting.delete(subdomain).

Get a single published website (hosting subdomain) by its subdomain label, including the Puter directory it serves from. The live site is reachable at https://<subdomain>.puter.site. Equivalent to PuterJS puter.hosting.get(subdomain).

List all websites (hosting subdomains) the authenticated Puter user has published. Each entry includes the subdomain (served at https://<subdomain>.puter.site) and the Puter directory it is hosted from. Use this to discover existing sites before creating or updating one. Equivalent to PuterJS puter.hosting.list().

Re-point an existing website (hosting subdomain) at a different Puter directory, changing which files https://<subdomain>.puter.site serves. Use this to attach content to a bare subdomain or to swap the served directory. Equivalent to PuterJS puter.hosting.update(subdomain, root_dir).

Add to the value already stored at a key and return the updated value — numbers are summed and arrays are appended to. Pass a plain value to add to the value itself, or an object mapping dot paths to the values to add at each path. To add an object as a value rather than as a path map, use kv_update. Equivalent to PuterJS puter.kv.add(key, value).

Decrement a numeric value in the Puter key-value store and return the new value. A key that does not exist starts at 0. Pass a number to decrement the value itself, or an object mapping dot paths to amounts. Equivalent to PuterJS puter.kv.decr(key, amount).

Delete a key from the Puter key-value store. Succeeds whether or not the key existed. Equivalent to PuterJS puter.kv.del(key).

Set how long a key lives, in seconds from now, after which it is removed. Equivalent to PuterJS puter.kv.expire(key, ttlSeconds).

Set the exact time a key is removed, as a Unix timestamp in seconds. Equivalent to PuterJS puter.kv.expireAt(key, timestampSeconds).

Read a key from the authenticated user's Puter key-value store. Returns { key, value }, where value is null when the key is not in the store — a stored null reads the same way, so use kv_list when you need to tell those apart. Equivalent to PuterJS puter.kv.get(key).

Increment a numeric value in the Puter key-value store and return the new value. A key that does not exist starts at 0. Pass a number to increment the value itself, or an object mapping dot paths to amounts to bump fields inside a stored object. Equivalent to PuterJS puter.kv.incr(key, amount).

List keys in the Puter key-value store, sorted by key. Returns keys only unless return_values is true. Every page is metered and a full listing reads the whole store, so narrow it with pattern and/or limit rather than listing everything. Equivalent to PuterJS puter.kv.list(options).

Remove one or more fields from the object stored at a key by dot path, returning the updated value. To delete the key itself use kv_del. Equivalent to PuterJS puter.kv.remove(key, ...paths).

Create or overwrite a key in the Puter key-value store. The value is stored as JSON (string, number, boolean, null, object, or array; max 400 KB). Pass expire_at to have the key removed at a given time. Equivalent to PuterJS puter.kv.set(key, value).

Update fields inside the object stored at a key without overwriting the whole value, returning the updated value. Equivalent to PuterJS puter.kv.update(key, pathAndValueMap).

Fetch a specific Puter / puter.js documentation page as Markdown by the topic path listed in puter_docs_index. Examples: "Workers/router" (the Worker router guide + canonical examples — read this before writing a worker), "Workers/create", "AI/chat", "KV/set", "FS/write", "Hosting/create". Use it to read the exact API and copy working examples before writing worker or puter.js code.

Load the index of Puter / puter.js documentation (from docs.puter.com/llms.txt): a list of every topic and its doc path, spanning the whole puter.js SDK — Workers (serverless functions), Hosting, FS, KV, AI (500+ models), Auth, and more. Call this FIRST to discover which doc to read, then fetch the page with puter_docs_get. Puter Workers and the tools in this server are designed to be used WITH puter.js and Puter authentication, so consult these docs before writing any worker or SDK code.

Get the authenticated Puter user's account info — including username, uuid, and the home_directory (/<username>) that ALL filesystem paths must live under. Call this first to learn your username so you can build valid absolute paths (e.g. "/<username>/portfolio/index.html") instead of invalid bare root paths. Equivalent to PuterJS puter.auth.getUser().

Deploy a serverless Puter Worker from a JavaScript file in the Puter filesystem and return its public URL. The worker file MUST define handlers on the global `router` object (router.get/router.post/router.put/router.delete) and may use the global puter.js SDK (`puter`) for storage, KV, AI, and more — authenticated as you, the deployer. Puter Workers are designed to be used WITH puter.js and Puter authentication, so BEFORE writing worker code load the router guide and examples via puter_docs_get with path "Workers/router". Typical flow: fs_write_file the worker code to a path (e.g. "~/workers/a…

Delete (undeploy) a Puter Worker by name, stopping its execution and releasing its URL. Does NOT delete the worker's source file in the filesystem. Equivalent to PuterJS puter.workers.delete(worker_name).

Call a deployed Puter Worker over HTTP as the authenticated user, automatically attaching the Puter auth header so the worker can act on the caller's resources via `user.puter`. Use this to invoke or test a worker endpoint. Equivalent to PuterJS puter.workers.exec(url, options).

Get a single deployed Worker by name, including its public URL and the source file path it serves (write new code to that file with fs_write_file to update it). Equivalent to PuterJS puter.workers.get(worker_name).

List all serverless Workers deployed by the authenticated Puter user, including each worker's name, public URL, and the source file it is deployed from (write to that file to update the worker). Equivalent to PuterJS puter.workers.list().