Skip to main content
This guide is meant to be read by your AI coding agent.
Tell your coding agent to look at this page and ask it to help you with Fimo.
You are an AI coding agent helping someone build and operate a Fimo website. Fimo owns everything after the build — content, editing, Branches, Environments, agents, and hosting — and exposes all of it through the fimo CLI. This page is the source of truth for getting set up. Work through the path that matches the user’s starting point. The bootstrap examples use fimo@latest, then switch to the site-pinned CLI after dependencies are installed. If the initiating prompt supplies a different exact CLI selector (for example fimo@staging), preserve that selector in the matching package-manager command.

​
Site knowledge

Before site recommendations, planning, design, copy, or code work, agents should read shared site knowledge. Fimo skills include this prerequisite; MCP clients can search for knowledge and execute knowledge.get with the site ID. Empty knowledge does not block work. Updates require an explicit request and permission.

​
1. Choose the onboarding path

Match the user’s request to one of three starting points. A site ID alone does not choose the path: Fimo Studio can create a brand-new site and hand you its ID before any code exists — that is still the create-new path.
  • Create a new Fimo site: run fimo init --project-id <projectId> when Fimo Studio supplied an ID. When starting from zero, infer a sensible directory name from the request (use my-site if there is no useful name) and run fimo init <dir>. Do not stop to ask what the site should be — initialize immediately. If the request already describes the site, build from that description; if not, initialize anyway and ask after the first preview. Finish this path with the first hosted preview in step 5.
  • Create a site for someone without a Fimo account: when the user has no account and doesn’t want to sign in now, run npx fimo@latest new --instructions and follow the guide it prints. It uses fimo new <dir> and hands the user a claim link instead of signing in.
  • Open an existing Fimo site: use its site ID to link and clone the existing code, then inspect it. If the ID is missing, ask for it. Setting up an existing site does not authorize a deployment.
  • Bring an external website or repository into Fimo: website migration is in alpha and not stable yet. Load the fimo-migration skill and follow its intake, QA, and final owner-approved deployment rules. If the source URL, repository, or export is missing, ask for it. Do not treat migration as fresh-site scaffolding.
A fresh fimo init uses Fimo’s current scaffold. In an existing Fimo site, keep its framework: detect it with fimo describe --json and load only its matching fimo-code reference. Do not invent a framework flag. When no framework is specified for a new site, the default scaffold is Next.js App Router. If the user’s request explicitly names React Router, Vite, Astro, or SvelteKit, pass --framework react-router, --framework vite, --framework astro, or --framework sveltekit during initialization. Existing sites keep their detected framework.

​
2. Install the CLI and sign in

The fimo CLI is published on npm. Run it without a global install using the user’s package manager:
Sign in with:
You cannot complete sign-in yourself. fimo login opens a browser loopback flow — ask the user to finish signing in there. fimo init (next step) will also trigger this automatically if there is no session yet. Once signed in, fimo whoami shows the active user and organization; switch organizations with fimo orgs switch.

​
3. Set up the site

If the user gave you a site ID, set it up with one command — replace <projectId> with the ID they gave you:
This signs you in if needed and links the site. A Studio-created site that has no code yet is scaffolded and pushed as a new site; a site with existing code is cloned. It also installs dependencies and offers to install the global Fimo bootstrap skill for your AI tool. Newly scaffolded sites contain AGENTS.md and CLAUDE.md. To start a brand-new site instead, infer a directory name and pass it to init:
fimo init is the single onboarding entry point (there is no separate fimo install or fimo create). In a non-interactive shell, make installation and skill setup explicit, replacing <agent-id> with the current coding agent:
For a new site, fimo init generates .fimo/project.json to link the local directory to the remote site. Treat it as read-only. Older sites may still use the legacy .fimo.settings.json link file.

​
Choose the primary locale before building

Treat language as part of new-site setup. If the initiating request names one or more languages, load the fimo-cli locales reference after init and use its typed lifecycle commands to configure the exact locale set and default. Never edit i18n.defaultLocale or i18n.locales directly in a linked site. Then update the framework-native locale boundary and document language default. The new shells keep the default locale unprefixed, so do not add /en, a language picker, or a global path-prefix strategy unless the requested site needs it. If the request has no locale signal, keep the shell’s en default and tell the user. For an existing site, preserve its current URL and locale behavior; see Locales.

​
4. Load the site context and skills

fimo init does not copy rich skills into the site. It can install one small global fimo bootstrap skill, which tells your agent to load the real skills from the CLI when needed.
  • Read the site rules: AGENTS.md, plus your tool’s variant if present (CLAUDE.md, .cursor/rules/fimo.mdc, .windsurfrules, GEMINI.md).
  • Load fimo-code on demand before writing schemas, entries, forms, t() labels, or fimo-react components. It resolves from the fimo package installed in the site, so the guidance matches the site’s runtime.
  • Load fimo-cli on demand for CLI workflows such as content operations, local development, and deploys. It comes from the CLI you are running.
Run these commands from inside the site after its dependencies are installed:
Add --ref <doc> to load a skill’s reference document. Always fetch skills through the CLI rather than reading a cached site copy. The site rule files came into existence mid-session, so your harness may not have auto-loaded them — read them before generating code. To set up another AI tool later:

​
5. Create the first hosted preview (new sites)

On the create-new path, setup is not complete when fimo init exits. Unless the user explicitly said not to deploy, create the site’s single first hosted preview after initialization and the context-loading steps above succeed — do not wait for a second request:
fimo deploy validates the site, commits pending changes, pushes, and syncs the preview sandbox; -m supplies the commit message because you run non-interactively. Return data.studio_url to the user. Run fimo preview url --json only when the hosted site URL itself is needed. If the initiating request described a concrete site, build a minimal meaningful first screen before this single deploy. If it did not, deploy the scaffolded site as-is and then ask what the user wants to build. This deploy creates a preview only — never add --publish. Publishing, and every deploy after this first one, requires the user’s explicit request. Opening an existing site and migrating do not auto-deploy merely because setup completed.

​
Choose the public URL before first publish

After the automatic first hosted preview on the create-new path, offer a cleaner free *.fimo.site URL before the first public publish if there is no custom domain and the default slug still looks generated or was never explicitly chosen. The free URL needs no DNS. Skip the offer if the user already chose the slug, attached a custom domain, or declined. Run fimo domains suggest-default --base "<brand>" --json, show the candidates, and ask the user to choose. A slug change determines the public URL, so claim nothing without explicit confirmation. After the user selects one, run fimo domains rename-default <slug> or fimo domains suggest-default --pick <slug>. Choosing the slug does not publish the site; the URL starts resolving after the first successful publish. Custom domains use the Pay as you go (or higher) workflow.

​
6. Quick reference

The full, current detail lives in the skills above — this is just a map. After first-time setup, start the local dev server with the package manager that matches the lockfile:
Work with the user against that server and iterate. Further deploys are on-demand: use plain fimo deploy for a hosted preview, and --publish only when the user explicitly wants to go live. Run any command with --help for its flags, and fimo --help for the full surface.