@getrefino/cli — the Refino installer

Refino lets site owners edit visible website copy in the browser while the repository stays the source of truth.

This package is how Refino is installed into a website. If you were asked to "install Refino", this is the package, and the command is:

npx @getrefino/cli init

The installed binary is named refino. Refino is the product; getrefino is only the npm namespace.

What Refino is

The owner of a coded website opens their real site, clicks a headline or a paragraph, rewrites it in place, and presses Save. The change is committed to the website's own repository and the normal deployment pipeline ships it.

• The copy lives in one JSON file in the repository (content/copy.json by default). That file is the only source of truth.
• An edit is a commit and a one-line diff. There is no CMS, no database and no sync step.
• It is builder-independent: it does not matter whether Claude Code, Cursor, Codex, Lovable, Replit or a human wrote the site.
• Removing Refino leaves the content exactly where it was.

Refino changes words. Your coding agent keeps doing features, layouts and components.

Install into a site

The order matters, and it starts on the Refino dashboard rather than in the repository.

1. Connect the site in the Refino dashboard (https://app.refino.dev). You give it the repository, the branch, where the copy file will live, and the URL the site is served from. Refino gives you a site id (site_…).

   • The branch must be the branch that will contain the Refino files and be deployed. Refino reads and commits the copy file on that branch and nowhere else.
   • The copy file does not have to exist yet. init writes it in step 2. Until the site is installed and deployed, the dashboard shows it as awaiting install; that is the expected state, not a fault.

2. Install into the repository, passing that site id:

   npx @getrefino/cli init --agent --yes --refino-site site_…

3. Hand .refino/AGENT_INSTRUCTIONS.md and .refino/plan.json to your coding agent and let it do exactly what they say.

4. Verify: npx @getrefino/cli verify, fixing only what it reports.

5. Commit and merge that work onto the branch the site is configured to use, and deploy it.

6. Open /edit on the deployed site.

If the site was connected to Refino again later — disconnected and reconnected, or moved to another account — it has a new site id, and step 2 is how the repository learns it. Re-run init --agent --yes --refino-site <new id>, commit and deploy.

Without --refino-site the same command sets up a self-hosted site, which holds its own editor password and repository token instead:

npx @getrefino/cli init --agent

init inspects the repository (framework, router, routes, package manager, auth, server, hosting, git), scans the pages for visible copy, proposes stable ids, and writes:

• the canonical copy file, with every selected string already in it
• isolated setup files under refino/, plus refino.config.json
• .refino/plan.json — the machine-readable migration plan
• .refino/AGENT_INSTRUCTIONS.md — what a coding agent must do next

Then check the result:

npx @getrefino/cli verify

Upgrading a site to a newer Refino

Move the @getrefino/* packages to the newer version, then run the command you installed with, from that version:

pnpm add @getrefino/core@<version> @getrefino/react@<version>   # or npm install / yarn add / bun add
npx @getrefino/cli@<version> init --agent --yes --refino-site site_…

init never changes a dependency already listed in package.json, and verify fails (package-versions) when the installed packages are not the release the generated integration was written for.

Updating the @getrefino/* packages is only half of an upgrade. Refino also generates runtime code into your repository (refino/, the /edit route), and installing a package never touches a file already committed there — so a site can be on the newest packages and still running an older release's integration. init is what moves that half.

You never have to delete or move a generated file. init refreshes every one it can prove you have not edited and reports it:

Updated Refino-generated integration:
  refino/refino-site.ts      0.1.0-rc.1 → 0.1.0-rc.3
  refino/copy-editing.tsx    0.1.0-rc.1 → 0.1.0-rc.3

A file you changed is never overwritten. It is listed as needing review, Refino's current version is written beside it as <file>.refino-new, and init exits non-zero rather than let a half-upgraded site look finished. Move your changes onto that version, replace the original with it, delete the .refino-new file, and run init again.

Refino knows which is which from .refino/generated.json, the record it writes of the exact bytes it generated — commit it with the rest. Sites installed before that file existed are recognised from the bytes of the older release, so they upgrade the same way.

refino verify reports the same three states — current, refreshable, needs review — without changing anything.

If you are a coding agent

1. Run npx @getrefino/cli init --agent --refino-site <site id> in the repository (the owner gets the site id from the Refino dashboard; without one, init --agent sets up a self-hosted site instead). Add --via claude|codex|gemini|grok|other so Refino knows which installation routes work.
2. Read .refino/AGENT_INSTRUCTIONS.md and .refino/plan.json and do exactly what they say. They are authoritative. They were generated from an inspection of this specific repository — do not invent integration steps, do not add a second content store, and do not widen the scope.
3. Run npx @getrefino/cli verify and fix only what it reports. Repeat until it passes.

If you are upgrading an existing installation rather than creating one, run the same init command from the newer version and read its output. A non-zero exit means a generated file has local changes Refino would have had to discard: resolve each one against the .refino-new file it left beside the original, then run init again. Do not delete or move generated files to get past it, and do not report the upgrade as done while init or verify still fails.

Commands

| Command | What it does | | --- | --- | | refino init | Inspect, plan, and write setup files + agent instructions | | refino inspect | Report the repository facts only | | refino scan | List the visible copy it found, with reasons | | refino plan | Print the migration plan (--format text\|json\|agent) | | refino verify | Check an installation and say exactly what is missing |

Every command takes --json for machine-readable output and --cwd <dir> to operate on another directory. refino init --dry-run shows what would be written without writing anything. No command overwrites an existing file, with one exception: init --refino-site <id> updates the generated refino/ constants module and the refino block of refino.config.json when they still name a different site, which is how a site reconnected in the Refino dashboard is re-recorded. Nothing you wrote by hand is touched.

Packages

@getrefino/cli is a thin command layer over @getrefino/onboarding. A site that has been onboarded ships only the runtime packages:

• @getrefino/core — content model and persistence contracts
• @getrefino/react — RefinoProvider and EditableText
• @getrefino/github — commits the copy file through the GitHub Contents API (self-hosted mode only)

https://refino.dev