Formation Cloud CLI

formation-cloud calls the Formation v3 operation front door. It also installs the Formation connector and reviewed creator Skills into exact local targets.

The package needs Node.js 22 or later. It has no runtime dependencies and does not import from a Formation checkout.

What this CLI does, and never does

It is a small MIT-licensed client for one HTTPS origin. Before an agent installs it, a person or the agent can read the source:

npm pack @getformation/[email protected] && tar -xzf getformation-cloud-cli-1.2.1.tgz && ls package/src package/connector

The code is under package/src; the connector is package/connector/SKILL.md.

• It calls only the configured FORMATION_CLOUD_URL origin over HTTPS and refuses redirects to any other origin.
• It writes only the Skill's Markdown files and one small JSON install receipt, into a target path the person names, after a dry run and an explicit --apply. A Skill is text an agent reads; the CLI never runs a file it downloads.
• It verifies every file against the server's manifest digests before it writes, and records a receipt so skill check can prove the install later.
• It stores nothing on the machine except those target files and receipts. It creates no schedule, service, or background process.
• Public discovery, following, and public Skill installation send no credential. FORMATION_AGENT_KEY is optional and is only sent as a bearer to the configured origin.

Install the exact public package from npm after the person approves the package installation:

npm install -g @getformation/[email protected]

Install the bundled Formation connector. The first command is a dry run. The second command writes the connector after separate human approval.

formation-cloud connector install --target /absolute/path/to/formation
formation-cloud connector install --target /absolute/path/to/formation --apply
formation-cloud connector check --target /absolute/path/to/formation

Set FORMATION_CLOUD_URL to the exact HTTPS Formation origin. Set FORMATION_AGENT_KEY only when an operation needs an authenticated machine scope. Following and public Skill installation need no credential.

The follow loop

An agent follows a creator by holding the creator's channel and the update cursor in its own durable memory. It polls Formation with the explicit channel set. When a release update arrives, the agent proposes the install or upgrade and waits for approval. Formation does not push updates.

formation-cloud discover
formation-cloud connector
formation-cloud channel_search '{"query":"formation"}'
formation-cloud channel_get '{"channelId":"channel_formation"}'
formation-cloud updates_reset '{"channelIds":["channel_formation"]}'
formation-cloud updates '{"cursor":"<saved updatesCursor>","channelIds":["channel_formation"]}'
formation-cloud skill_search '{"query":"formation"}'
formation-cloud skill install formation-clear-technical-writing --target /absolute/path/.agents/skills/formation-clear-technical-writing
formation-cloud skill install formation-clear-technical-writing --target /absolute/path/.agents/skills/formation-clear-technical-writing --apply
formation-cloud skill check --target /absolute/path/.agents/skills/formation-clear-technical-writing

updates_reset returns the current snapshot and, on the final page, updatesCursor. updates continues from a saved cursor with the same channelIds. A different channel or interest set returns cursor_reset_required. A release update carries the Skill name and the exact installable artifactRevisionId.

Skill installation

skill install accepts a Skill name or an artifact revision identifier. A Skill name such as formation-clear-technical-writing resolves through skill_search to the one current artifact whose creator handle and collection slug form that name. An unknown name fails with skill_not_found. A name that matches more than one current artifact fails with skill_ambiguous. An identifier such as skillrev_<sha256> installs that exact revision.

Connector and Skill installation are dry runs unless you pass --apply. Retrieval and dry runs do not mutate Formation. A Skill upgrade also needs --replace and --expected-installed-manifest with the exact SHA-256 digest from the current local receipt. There is no force, adopt, default-target, home-target, root-target, legacy route, alias, or MCP file-write mode.

The installer accepts only strict UTF-8 Markdown manifests. It verifies the configured origin, response URLs, paths, limits, file hashes, and aggregate manifest digest before it writes. A local receipt .formation-cloud-install.json records the installer version, origin, artifact revision, manifest digest, and installed file hashes. skill check reports current, withdrawn, stale, or conflict. It never deletes an installed Skill.

Optional account

The person can create a narrow credential in the browser to sync follows across agents with follow, unfollow, and follows_list, or to reach restricted knowledge. The person stores the credential outside chat and shell history and reloads or reconnects after secret placement. An authenticated updates_reset without channelIds polls the account follows.

Connector version 1.2.1 is a clean install. It does not replace an older connector target. Remove the exact old connector target first, then install 1.2.1 into the absent path. Repeating an identical receipt-owned 1.2.1 install is unchanged. A Skill target installed by an earlier CLI version reports conflict from skill check and cannot be upgraded in place. Remove that target, then install the Skill again with the current CLI.