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 examples use fimo@latest. If the initiating prompt supplies a different exact CLI selector (for example npx fimo@staging), preserve that selector for every fimo command in this flow.

​
1. Choose the onboarding path

Match the user’s request to one of three starting points. A project ID alone does not choose the path: Fimo Studio can create a brand-new project and hand you its ID before any code exists — that is still the create-new path.
  • Create a new Fimo project: 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.
  • Open an existing Fimo project: use its project ID to link and clone the existing code, then inspect it. If the ID is missing, ask for it. Setting up an existing project does not authorize a deployment.
  • Bring an external website or repository into Fimo: website migration is still in development. 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-project scaffolding.
A fresh fimo init uses Fimo’s current scaffold. In an existing Fimo project, 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 project, 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 projects keep their detected framework.

​
2. Install the CLI and sign in

The fimo CLI is published on npm. For one-off setup you can run it with npx:
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 project

If the user gave you a project ID, set it up with one command — replace <projectId> with the ID they gave you:
This signs you in if needed and links the project. A Studio-created project that has no code yet is scaffolded and pushed as a new site; a project with existing code is cloned. It also installs dependencies and offers to install the global Fimo bootstrap skill for your AI tool. Newly scaffolded projects contain AGENTS.md and CLAUDE.md. To start a brand-new project 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 — for example npx fimo@latest init my-site -y --install --skills --agents=<agent-id>, replacing <agent-id> with the current coding agent.
For a new project, fimo init generates .fimo/project.json to link the local directory to the remote project. Treat it as read-only. Older projects may still use the legacy .fimo.settings.json link file.

​
Choose the primary locale before building

Treat language as part of new-project 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 project. 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 project, preserve its current URL and locale behavior; see Locales.

​
4. Load the project context and skills

fimo init does not copy rich skills into the project. 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 project 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 project, so the guidance matches the project’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 project 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 project copy. The project 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 projects)

On the create-new path, setup is not complete when fimo init exits. Unless the user explicitly said not to deploy, create the project’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 project, 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 project 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, work with the user against a local dev server (pnpm dev / npm run dev / yarn dev / bun dev — match the lockfile) 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.