yarn microfeed command reference

This is the canonical capability reference for the official @microfeed/cli package, including the yarn microfeed command available inside a microfeed clone. For a shorter workflow, start with Manage content with the microfeed CLI.

Contents

• Run the CLI
• Agent skill
• Authentication and safety
• Command summary
• Global options
• login
• logout
• instances
• item
• item list
• item search
• item get
• item create
• item update
• item delete
• media
• media upload
• api
• Output and errors
• Saved instances and credentials
• Environment variables
• Built-in help

Run the CLI

@microfeed/cli requires Node.js 22.12 or newer. Choose the invocation that matches where you are working.

Context	Command	Installation behavior
Inside a microfeed clone	yarn microfeed …	Uses the local workspace after the repository’s normal yarn install. It does not require a CLI build, registry download, or global installation.
Another Yarn project	yarn add -D @microfeed/cli, then yarn microfeed …	Uses the project-local package and binary.
One-off use	yarn dlx @microfeed/cli …	Downloads a temporary package for this run.
Optional global installation	microfeed …	Uses the same published executable, but global installation is not the recommended path.

The examples below use yarn microfeed. Replace that prefix with yarn dlx @microfeed/cli or microfeed when using one of the other modes.

Agent skill

Inside a microfeed clone, agent hosts discover the repository-owned manage-microfeed-content skill at .agents/skills/manage-microfeed-content/. The published npm tarball contains the identical skill at dist/skills/manage-microfeed-content/ for agent hosts or skill installers that distribute skills with the CLI. The repository copy is canonical, and the package check fails when the bundled copy differs.

The skill teaches invocation selection, site and instance vocabulary, connection identity, browser-consent handoff, deterministic output, the difference between standalone media, item images, and media attachments, credential safety, and deletion confirmation.

Authentication and safety

The CLI uses browser authorization for interactive work and an existing API key for unattended work. Both result in a Bearer credential; browser login does not make the API credential-free.

Browser login:

1. Verifies /.well-known/microfeed.json identifies the target as microfeed.
2. Loads the official CLI authorization endpoints from the same site URL.
3. Rejects redirects or authorization endpoints hosted at another site.
4. Opens administrator login and consent in the browser.
5. Uses authorization-code flow, S256 PKCE, and state validation.
6. Listens for the callback only at http://127.0.0.1:8977/callback.
7. Requests content:read, content:write, and offline_access.

The person operating the instance must approve or deny access in the browser. A coding agent may start login, but must pause for that user-controlled step. Login requires HTTPS except for http://localhost and http://127.0.0.1 test instances. If a site’s public URL changes, log in again.

New instances keep API access disabled by default. Browser login can be saved while access is off, but content commands return 404 until the site owner signs in to the admin dashboard, opens API → API Settings, and turns on Enable API access. An AI agent must pause for this browser-only change and must not request the owner’s dashboard password, API key, or CLI credential.

For every authenticated REST request, the CLI:

• injects the selected Bearer credential and refreshes CLI credentials when needed;
• accepts only the selected site URL;
• does not follow redirects or forward credentials through one;
• never prints access tokens, refresh tokens, API keys, or client secrets.

Command summary

Command	Purpose	Local or remote change
login <site-url>	Authorize the official public CLI client in a browser and save an instance for this computer connection.	Creates or replaces a local encrypted saved instance after browser consent.
logout	Revoke this computer’s selected credential family and remove its saved instance locally.	Leaves the server-side connection listed as Inactive until the owner revokes it.
instances list	List saved instances and the current selection.	Read-only.
instances use <name>	Select the default saved instance.	Changes only the local current-instance pointer.
instances remove <name>	Remove a saved instance locally without contacting the site.	Changes only the local instance store.
item list	Read a page of the feed.	Read-only.
item search <query>	Search item titles or stored plain-text content.	Read-only.
item get <item-id>	Read one item.	Read-only.
item create	Create an item from flags or JSON.	Creates remote content.
item update <item-id>	Update an item from flags or JSON.	Changes remote content.
item delete <item-id>	Delete an item after exact-ID confirmation.	Permanently deletes remote content.
media upload <file>	Upload standalone media for rich content or later API use.	Creates a remote media object but does not edit an item.
api <method> <path>	Call a relative /api/v1/… REST endpoint.	Depends on the method and endpoint.

Global options

Global options may appear before or after a command and its arguments.

Option	Meaning
--instance <name>	Use a saved instance instead of the current one. This takes precedence over MICROFEED_INSTANCE.
--json	Write deterministic JSON to standard output. API responses include status, ok, safe response headers, and body; a 404 also includes safe recovery guidance.
-h, --help	Show help for the selected command or subcommand without running it.

When MICROFEED_API_KEY is set, --instance selects its site URL from a saved instance; it does not cause the saved browser credential to be used.

yarn microfeed login

Purpose: Verify and authorize a microfeed site, then save it as the current instance.

Changes: After browser approval, creates or replaces a local encrypted saved instance and makes it current. It does not expose a credential in terminal output.

yarn microfeed login <site-url> [--instance <name>] [--connection-name <computer-name>]

Option	Meaning
--instance <name>	Save the site under this local instance name. Names contain 1–64 letters, numbers, dots, underscores, or hyphens.
--connection-name <computer-name>	Label this computer under Account settings → App access. Names contain 1–64 printable characters. Without it, the CLI uses the computer hostname or a privacy-neutral platform label.

Without --instance, the CLI derives the name from the site hostname. Use the URL that opens the public microfeed site. It may use a custom domain or the generated workers.dev address; do not use a dashboard path such as https://feed.example.com/admin. Login requests the official microfeed-cli public client with the fixed loopback callback. The callback port must be available, and browser approval must complete within five minutes.

The CLI generates a random, non-secret connection ID for each saved site and stores it separately from the encrypted token bundle. Logging the same saved site in again reuses that connection ID, replaces the old token family, and updates the connection name without creating a duplicate computer entry.

Login may succeed while API access is disabled. Before running a content command on a new instance, the site owner signs in to the admin dashboard, opens API → API Settings, and turns on Enable API access. If an agent is operating the CLI, it pauses and asks the owner to complete that browser step.

yarn microfeed login https://feed.example.com \
  --instance production \
  --connection-name "Home Mac"

With --json, success returns the saved name, canonical siteUrl, verified instanceId, and non-secret connectionName. It never returns the connection ID or a credential.

yarn microfeed logout

Purpose: Revoke this computer’s selected credential family and remove its saved instance locally.

Changes: Attempts to revoke the refresh token, or the access token when no refresh token exists, then deletes the saved instance locally. If it was current, the alphabetically first remaining instance becomes current.

yarn microfeed logout [--instance <name>]

If revocation cannot be delivered, logout still removes the saved instance. The server-side authorization remains visible as Inactive under Account settings → App access until the owner revokes it. An owner can revoke one computer connection without interrupting another, or revoke all microfeed CLI connections together.

Use instances remove instead when local credentials are unreadable or when you intentionally want a local-only removal.

yarn microfeed instances

Manage locally saved instances.

yarn microfeed instances list

Purpose: List instance names, site URLs, instance IDs in JSON output, and the current selection.

Changes: None.

yarn microfeed instances list [--json]

Human-readable output marks the current instance with *. JSON output returns an instances array whose entries contain name, siteUrl, instanceId, connectionName, and current.

yarn microfeed instances use

Purpose: Select the default saved instance for later commands.

Changes: Updates only the local current-instance pointer.

yarn microfeed instances use <name> [--json]

yarn microfeed instances remove

Purpose: Remove a saved instance locally without decrypting or revoking its CLI credentials.

Changes: Deletes the saved instance locally. It does not contact the site.

yarn microfeed instances remove <name> [--json]

Use logout for the normal revoke-and-remove workflow. Use remove for local cleanup or recovery when the keychain entry is unavailable.

yarn microfeed item

List, search, read, create, update, or delete content items. An <item-id> is the stable ID returned by item list, item search, or item get, such as 0HGJLSML3P1. Create and update accept either common flags or one JSON object from --input; they reject mixed input forms. Delete is permanent and requires an exact item-ID confirmation.

yarn microfeed item <list|search|get|create|update|delete> [arguments] [options]

yarn microfeed item list

Purpose: Read a page from GET /api/v1/feed/.

Changes: None.

yarn microfeed item list [options]

Option	Meaning
--limit <1-300>	Maximum number of items to return.
--next-cursor <cursor>	Continue forward from a response cursor.
--prev-cursor <cursor>	Continue backward from a response cursor.
--sort <field>	Use created_at, updated_at, published_at, newest_first, or oldest_first.
--order <direction>	Use asc or desc.

yarn microfeed item list --instance production --limit 25 --json

yarn microfeed item search

Purpose: Search items through GET /api/v1/search/.

Changes: None.

yarn microfeed item search <query> [options]

The query contains 1–200 characters. Unquoted terms use implicit AND matching, and the final unquoted term supports prefix matching. Put matching single or double quotes inside the query for an exact phrase. Exact matches rank before typo-tolerant title matches; quoted phrases and content are never fuzzy matched.

Option	Meaning
--fields <fields>	Search title, content, or title,content. The default searches both.
--status <statuses>	Filter by a comma-separated list of published, unlisted, or unpublished. The default includes all three.
--date-published-ms-gt <milliseconds>	Return items published strictly after this Unix timestamp in milliseconds.
--date-published-ms-lt <milliseconds>	Return items published strictly before this Unix timestamp in milliseconds.
--limit <1-100>	Maximum matches to return; defaults to 20.
--next-cursor <cursor>	Continue forward using a cursor returned for the same query and filters.

Search only titles for hello:

yarn microfeed item search hello --fields title --instance production --json

Keep the shell’s outer quotes separate from the exact phrase quotes that the search API receives:

yarn microfeed item search '"season finale"' \
  --fields title,content \
  --status published,unlisted \
  --json

Without --json, the response body is formatted on standard output. With --json, the normal CLI API envelope contains the search response under body, including items, safe highlight segments, and an optional next_cursor.

yarn microfeed item get

Purpose: Read one item by ID or an item-page slug ending in its ID.

Changes: None.

yarn microfeed item get <item-id>

yarn microfeed item get 0HGJLSML3P1 --instance production --json

Item input

item create and item update accept either common flags or one JSON object. Do not combine the two input forms.

Common flag	API field	Meaning
--title <text>	title	Item title.
--content-html <html>	content_html	HTML body.
--date-published <datetime>	date_published	ISO 8601 publication date and time.
--attachment-file <path>	attachments[0]	Upload one local main media attachment, which becomes the JSON Feed attachment and RSS enclosure. Do not combine with --input.
--image <url>	image	An already-hosted absolute item cover-image URL. This is not a local file path or media attachment.
--image-file <path>	image	Upload one local AVIF, GIF, JPEG, PNG, or WebP cover image. This is not the media attachment. Do not combine with --image or --input.
--status <status>	status	Prefer published, unlisted, or unpublished.
--url <url>	url	Canonical item URL.
`–input <file	->`	Entire JSON body

JSON input may use the complete item schema documented by the target instance, including fields not represented by the common flags.

An item image is cover art or a thumbnail and uses the top-level image field. A media attachment is the item’s one main audio, video, document, or image file. It uses attachments[0] in JSON Feed and becomes <enclosure> in RSS. These fields are independent: attaching a full-resolution image does not set the cover image, and setting a cover image does not create an enclosure.

Standalone media is an uploaded file that the CLI does not assign to an item field. Use media upload for an image that will be embedded inside content_html, then save its permanent media_url in the HTML. This is the command-line counterpart to Insert image in the admin visual editor.

--attachment-file supports MP3, M4B, FLAC, MP4, PDF, DOC, DOCX, XLSX, PPT, PPTX, TXT, AVIF, GIF, HEIC, JPEG, JPG, PNG, WebP, and CR2. The CLI infers the attachment category and MIME type from the extension and records its byte size. Supplying it on update replaces the existing main attachment.

For either local-file option, the CLI asks the selected instance for a short-lived, same-site upload URL, sends only the file bytes to that URL without a Bearer credential, and saves the returned permanent media URL on the item. It refuses upload redirects and upload URLs hosted at another site. Standard output contains only the final item API response; the short-lived upload URL is never printed.

To reference already-hosted media with JSON input, use one attachment:

{
  "attachments": [{
    "category": "audio",
    "url": "https://cdn.example.com/episode.mp3",
    "mime_type": "audio/mpeg",
    "size_in_bytes": 277000,
    "duration_in_seconds": 1262
  }]
}

Use category: "external_url" for a linked web page rather than a file.

yarn microfeed item create

Purpose: Create an item with POST /api/v1/items/.

Changes: Creates remote content.

yarn microfeed item create [item flags | --input <file|->]

yarn microfeed item create \
  --instance production \
  --title "Release notes" \
  --content-html "<p>What changed.</p>" \
  --status published \
  --json

yarn microfeed item create \
  --instance production \
  --input item.json \
  --json

yarn microfeed item create \
  --instance production \
  --title "Episode 1" \
  --attachment-file ./episode.mp3 \
  --status published \
  --json

yarn microfeed item create \
  --instance production \
  --title "Full-resolution photo" \
  --attachment-file ./original.png \
  --status unlisted \
  --json

yarn microfeed item create \
  --instance production \
  --title "Photo update" \
  --image-file ./cover.png \
  --status unlisted \
  --json

For item create --attachment-file, the item must exist before the instance can prepare its attachment upload. The CLI creates the item, uploads the file, then updates the new item with attachments[0]. If upload or update fails after creation, the error reports the new item ID so it can be inspected or repaired.

yarn microfeed item update

Purpose: Replace or update an item with PUT /api/v1/items/{item-id}/.

Changes: Changes remote content.

yarn microfeed item update <item-id> [item flags | --input <file|->]

yarn microfeed item update 0HGJLSML3P1 \
  --instance production \
  --input - \
  --json < item.json

yarn microfeed item update 0HGJLSML3P1 \
  --instance production \
  --attachment-file ./episode.mp3 \
  --json

yarn microfeed item update 0HGJLSML3P1 \
  --instance production \
  --image-file ./cover.png \
  --json

yarn microfeed item delete

Purpose: Permanently delete one item.

Changes: Deletes remote content after exact-ID confirmation.

yarn microfeed item delete <item-id> [--confirm <item-id>]

Option	Meaning
--confirm <item-id>	Confirm a non-interactive deletion. The value must exactly match the positional item ID.

In an interactive terminal, omitting --confirm prompts you to type the exact item ID. In non-interactive use, --confirm is required and its value must exactly equal the positional ID. There is no generic --yes option.

yarn microfeed item delete 0HGJLSML3P1 \
  --instance production \
  --confirm 0HGJLSML3P1 \
  --json

Before an agent runs this command, it must report the selected saved-instance name and exact item ID, explain that deletion is permanent, and receive approval.

yarn microfeed media

Upload standalone media for rich content or later use by another documented API field.

yarn microfeed media upload <file> [--item-id <item-id>]

The upload creates a remote media object and returns its permanent URL. It does not edit an item. Use item --help when you instead want to set item cover art or the main RSS enclosure.

yarn microfeed media upload

Purpose: Upload one supported local file and return permanent, safe media metadata.

Changes: Creates a stored media object. It does not insert the object into an item, and an object that is never referenced remains stored because the CLI has no media-delete command.

yarn microfeed media upload <file> \
  [--item-id <item-id>] \
  [--instance <name>] \
  [--json]

Option	Meaning
--item-id <item-id>	Associate the prepared upload with an existing item. Required for audio, video, and document files; optional for images.
--instance <name>	Use this saved instance instead of the current one.
--json	Return category, media_url, mime_type, and size_in_bytes.

Supported extensions are MP3, M4B, FLAC, MP4, PDF, DOC, DOCX, XLSX, PPT, PPTX, TXT, AVIF, GIF, HEIC, JPEG, JPG, PNG, WebP, and CR2. The CLI infers the category and MIME type from the extension. Images can be uploaded without an item ID, matching the admin visual editor’s inline-image flow. The current REST contract requires an existing item ID for audio, video, and document uploads.

For an inline rich-text image, upload first:

yarn microfeed media upload ./diagram.png --instance production --json

{
  "category": "image",
  "media_url": "https://feed.example.com/media/production/images/diagram.png",
  "mime_type": "image/png",
  "size_in_bytes": 80633
}

Then use media_url in the item’s HTML and create or update the item through JSON input:

{
  "content_html": "<p>Before the image.</p><img src=\"https://feed.example.com/media/production/images/diagram.png\" alt=\"Diagram\"><p>After the image.</p>"
}

yarn microfeed item update 0HGJLSML3P1 \
  --instance production \
  --input item.json \
  --json

Without --json, successful output is only the permanent URL plus a newline, which makes the result easy to compose in a shell. The CLI never outputs the short-lived presigned URL. Reference the returned permanent URL promptly so an unused upload is not left behind.

For non-image media, supply the target item:

yarn microfeed media upload ./episode.mp3 \
  --item-id 0HGJLSML3P1 \
  --instance production \
  --json

yarn microfeed api

Purpose: Call a documented REST operation while the CLI selects, injects, and refreshes credentials.

Changes: Depend on the HTTP method and API endpoint.

yarn microfeed api <method> </api/v1/path> \
  [--input <file|->] \
  [--header <name:value>]…

Option	Meaning
`–input <file	->`
--header <name:value>	Add a request header. Repeat the option for multiple headers.

The path must be relative, begin with /api/v1/, and remain on the selected site URL. The CLI rejects caller-provided Authorization, Cookie, and Host headers. It returns an error rather than following a redirect.

--input reads UTF-8 request bodies and does not upload binary files or follow prepared upload URLs. Use media upload <file> for inline or standalone media, --attachment-file <path> for a local media attachment/RSS enclosure, and --image-file <path> for local item cover art.

Quote paths containing ? or & so the shell passes them as one argument.

yarn microfeed api GET "/api/v1/feed/?limit=3" \
  --instance production \
  --json

yarn microfeed api POST /api/v1/items/ \
  --instance production \
  --input item.json \
  --header "Content-Type: application/json" \
  --json

Output and errors

Without --json, API response bodies go to standard output. JSON response bodies are pretty-printed, while text bodies are preserved. Diagnostics and a non-success HTTP status message go to standard error.

With --json, API commands return one JSON object:

{
  "body": {},
  "headers": {
    "content-type": "application/json"
  },
  "ok": true,
  "status": 200
}

A 404 result adds a structured recovery object with a stable code, a documentation URL, and safe instructions for the owner or agent. It does not contain a credential or assume the dashboard uses the default /admin/ path.

{
  "body": "404",
  "headers": {
    "content-type": "text/plain; charset=utf-8"
  },
  "ok": false,
  "status": 404,
  "recovery": {
    "code": "api_access_or_resource_not_found",
    "documentationUrl": "https://docs.microfeed.org/api/authentication/#enable-the-api",
    "instructions": [
      "New microfeed instances keep API access disabled by default.",
      "The site owner should sign in to the admin dashboard, open API → API Settings, and turn on Enable API access.",
      "If you are an AI agent, pause and ask the site owner to complete that browser step; do not request their dashboard password, API key, or CLI credential.",
      "After API access is enabled, retry the same command. If it is already enabled, verify that the requested resource and /api/v1/ path exist."
    ],
    "message": "API access may be disabled, or the requested resource may not exist."
  }
}

Only safe response headers are included: cache-control, content-length, content-type, etag, last-modified, and x-request-id. Saved-instance commands also return one deterministic JSON object when --json is present. media upload --json returns category, permanent media_url, mime_type, and size_in_bytes; it never returns the prepared upload URL.

CLI validation failures, authentication failures, transport failures, and non-success API responses set a nonzero exit status. Missing authentication is never an interactive token prompt; the error tells you to run login or select a saved instance. Content commands require API access to be enabled. Because a disabled API intentionally returns 404, that status can mean either that the requested resource does not exist or that API access is disabled. The CLI explains that new instances default to disabled, directs the owner to API → API Settings → Enable API access, tells an AI agent to pause for that browser step, and links to the API setup guide.

Saved instances and credentials

Saved instances record the verified instance ID, site URL, authorization endpoints, and an AES-256-GCM encrypted token bundle. The encryption key exists only in the operating-system keychain under the microfeed-cli service. The CLI never falls back to plaintext storage.

The instance store is instances.json in the platform configuration directory:

• $XDG_CONFIG_HOME/microfeed, or ~/.config/microfeed when XDG_CONFIG_HOME is unset;
• %APPDATA%\microfeed on Windows.

The directory and file are created with owner-only permissions where the platform supports them. Do not read, print, copy, or commit the encrypted store. If the keychain is unavailable or locked, the CLI fails without storing credentials. Install the optional @napi-rs/keyring dependency when the published package manager did not install it for the current platform.

CLI credentials are refreshed automatically when they are within one minute of expiry. A successful refresh rotates the locally encrypted bundle. When refresh fails or no refresh token exists, log in again.

Environment variables

Variable	Purpose
MICROFEED_API_KEY	Use an existing API key as the Bearer credential. It takes precedence over saved browser credentials and is never persisted. Supply it through a CI secret manager.
MICROFEED_URL	Set the API-key target site URL when no selected saved instance supplies one. HTTPS is required except for local loopback site URLs.
MICROFEED_INSTANCE	Select a saved instance when --instance is omitted.
MICROFEED_CONFIG_DIR	Override the instance-store directory. Intended for isolated environments and tests; it does not weaken encryption or replace the OS keychain.

Never place a credential directly in a command, checked-in file, log, generated example, or agent conversation.

Built-in help

yarn microfeed --help
yarn microfeed help
yarn microfeed login --help
yarn microfeed instances use -h
yarn microfeed item create --help
yarn microfeed help item delete
yarn microfeed media upload --help
yarn microfeed api --help

Top-level help defines inputs such as <site-url>, <name>, <item-id>, and <file|-> with legitimate examples. Every command and nested subcommand supports both -h and --help, including after other arguments, and the equivalent help [command [subcommand]] form. Command help lists its purpose, exact usage, every option, input formats, changes or safety constraints, examples, and a link to the matching section of this page. Help never starts browser login or sends an API request.

Maintaining this reference

The shared human-and-agent help inventory lives in packages/cli/src/help.ts. Command dispatch lives in packages/cli/src/index.ts, and command behavior lives in packages/cli/src/commands.ts, with authentication, HTTP, and saved-instance storage guarantees in the neighboring CLI modules. Tests require every help topic and option to appear in this canonical reference and verify the workspace and packed package render the same help. When behavior changes, update the implementation, help inventory, tests, and this page together.