fimo 2.10.1-staging.1 → 2.10.1-staging.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/assets/skills/fimo-cli/SKILL.md +57 -139
- package/assets/skills/fimo-cli/SKILL.studio.md +42 -0
- package/assets/skills/fimo-cli/references/branches.md +43 -106
- package/assets/skills/fimo-cli/references/content/bulk.md +48 -0
- package/assets/skills/fimo-cli/references/content/entries.md +54 -0
- package/assets/skills/fimo-cli/references/content/localized.md +56 -0
- package/assets/skills/fimo-cli/references/content/schemas.md +29 -0
- package/assets/skills/fimo-cli/references/content/sql.md +57 -0
- package/assets/skills/fimo-cli/references/content.md +33 -272
- package/assets/skills/fimo-cli/references/deploy.md +35 -126
- package/assets/skills/fimo-cli/references/domains.md +38 -131
- package/assets/skills/fimo-cli/references/forms.md +1 -1
- package/assets/skills/fimo-cli/references/init.md +36 -170
- package/assets/skills/fimo-cli/references/locales.md +2 -2
- package/assets/skills/fimo-cli/references/projects.md +1 -1
- package/assets/skills/fimo-code/references/design.md +42 -126
- package/assets/skills/fimo-migration/SKILL.md +114 -408
- package/assets/skills/fimo-migration/references/content-delivery.md +67 -0
- package/assets/skills/fimo-migration/references/frameworks/nextjs.md +1 -1
- package/assets/skills/fimo-migration/references/qa/browser.md +41 -0
- package/assets/skills/fimo-migration/references/qa/guardrails.md +95 -0
- package/assets/skills/fimo-migration/references/qa/results.md +78 -0
- package/assets/skills/fimo-migration/references/qa.md +102 -383
- package/assets/skills/fimo-migration/references/questions-and-improvements.md +77 -168
- package/assets/skills/fimo-migration/references/setup.md +90 -0
- package/assets/skills/fimo-migration/references/workers/validator.md +2 -2
- package/assets/skills/fimo-migration/references/workers.md +1 -1
- package/assets/skills/fimo-migration/references/workflow.md +117 -171
- package/assets/skills/fimo-studio/SKILL.md +12 -11
- package/assets/skills/fimo-studio/references/ai-chat/agents.md +46 -0
- package/assets/skills/fimo-studio/references/ai-chat/default-agents.md +57 -0
- package/assets/skills/fimo-studio/references/ai-chat/routines.md +53 -0
- package/assets/skills/fimo-studio/references/ai-chat.md +39 -76
- package/assets/skills/fimo-studio/references/custom-domains.md +2 -2
- package/assets/skills/fimo-studio/references/publish-and-deploy.md +1 -1
- package/dist/cli/bundle.json +1 -1
- package/dist/cli/index.js +38 -17
- package/package.json +8 -8
- package/templates/astro/package.json +3 -3
- package/templates/nextjs/package.json +4 -4
- package/templates/react-router/package.json +5 -5
- package/templates/sveltekit/package.json +3 -3
- package/templates/vite/package.json +5 -5
|
@@ -9,150 +9,68 @@ description: >-
|
|
|
9
9
|
|
|
10
10
|
# Fimo CLI
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
This skill covers CLI workflows. For code (schema JSON, generated clients, primitives, framework adapters), load `fimo skills get fimo-code`. For the flags of one command, run `fimo <command> --help`.
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
## Every task
|
|
15
15
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
Before site planning, recommendations, design, copy, content, or code work, read the site's
|
|
23
|
-
knowledge: `fimo knowledge get --project <id> --json` (omit `--project` in a linked checkout).
|
|
24
|
-
Use the selected CLI invocation. Load `fimo skills get fimo-cli --ref knowledge` for refresh,
|
|
25
|
-
empty-state, and explicit-write rules. This prerequisite also applies when entering this skill directly.
|
|
26
|
-
|
|
27
|
-
## Running the CLI
|
|
28
|
-
|
|
29
|
-
Use **`npx fimo@latest`** by default. If the initiating prompt supplies another Fimo CLI selector, such as `npx fimo@staging` or `npx fimo@0.14.0`, preserve that selector for every Fimo command in the same flow. Do **not** install `fimo` globally.
|
|
30
|
-
|
|
31
|
-
The examples in this skill and its references use `fimo <command>` as shorthand. Execute them with the selected invocation above.
|
|
32
|
-
|
|
33
|
-
## Output for agents: `--json` is the stable contract
|
|
34
|
-
|
|
35
|
-
Every command accepts a global `--json` flag (or `FIMO_OUTPUT=json` env) and emits exactly one structured envelope on stdout:
|
|
16
|
+
- **Invocation:** run `npx fimo@latest`, unless the prompt gives another selector, such as `npx fimo@staging` or `npx fimo@0.14.0`. Then use that selector for every Fimo command in the flow. Do not install `fimo` globally. This skill writes `fimo` for the selected invocation.
|
|
17
|
+
- **Site knowledge:** before planning, recommendations, design, copy, content, or code work, read `fimo knowledge get --json` (add `--project <id>` outside a linked checkout). Rules: `--ref knowledge`.
|
|
18
|
+
- **Project link:** `.fimo/project.json` links the folder to the site. Never edit it.
|
|
19
|
+
- **Branch:** site commands act on the Fimo Branch that matches the current git branch, and print its name. `--branch <name>` changes the Branch for one command. Analytics reads use `prod` by default. Switch Branches with `fimo checkout <name>` (`--ref branches`).
|
|
20
|
+
- **Output:** pass `--json` and read `data`. Branch on `error.code`, not on the message, and follow `hint`. JSON mode never prompts, so give each answer as a flag (`--yes`, `--org <id>`, `-m <message>`).
|
|
36
21
|
|
|
37
22
|
```json
|
|
38
23
|
{ "status": "ok", "command": "<name>", "schema_version": 1, "data": { ... }, "hint"?: "...", "warnings"?: [...] }
|
|
39
24
|
{ "status": "error", "command": "<name>", "schema_version": 1, "error": { "code": "UPPER_SNAKE_CASE", "message": "...", "hint"?: "..." } }
|
|
40
25
|
```
|
|
41
26
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
fimo skills
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
fimo
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
-
|
|
91
|
-
-
|
|
92
|
-
- "Declare Pages routes / configure Pages sources or route params / control what Studio shows for a route" → `references/pages.md`
|
|
93
|
-
- "Add a contact / signup / feedback / newsletter form" → `references/forms.md` (workflow) **+ run `fimo skills get fimo-code --ref forms` for the JSON spec and generated client**
|
|
94
|
-
- "View form submissions / who filled out the contact form / inspect what users sent / how many signups" → `references/forms.md` § Reading submissions
|
|
95
|
-
- "Upload, inspect, replace, safely remove, or permanently destroy an image / hero / cover / existing media file" → `references/assets.md` **+ run `fimo skills get fimo-code --ref assets` for the `FimoMedia` shape and rendering**
|
|
96
|
-
- "Generate AI image / video / draft preview / image edit / cover from a prompt" → `references/media.md` (task commands, quality, recipes, and verification) **+ run `fimo skills get fimo-code --ref assets` for the `FimoMedia` shape if you'll plug the result into UI**
|
|
97
|
-
- "Add labels / update static copy / fix missing `t()` values" → `references/labels.md` (workflow) **+ run `fimo skills get fimo-code --ref labels` and load the detected framework reference**
|
|
98
|
-
- "Enable locales / configure default locale / integrate an existing locale system" → `references/locales.md` **+ run `fimo skills get fimo-code --ref locales` and load the detected framework locale reference**
|
|
99
|
-
- "What's in this project / show the project structure / describe the project / what schemas does it have / how many routes / project tree / show me what's here" → `references/describe.md`
|
|
100
|
-
- "Deploy / publish / go live / push my changes" → `references/deploy.md`
|
|
101
|
-
- "Add a redirect / security headers / CSP / HSTS / clean URLs / trailing slash" → `references/hosting.md`
|
|
102
|
-
- "Get the preview URL / open the preview / what's the URL for this Branch / refresh the preview link / I just want to see the site / the preview URL stopped working" → `references/preview.md`
|
|
103
|
-
- "Check the site in a browser / SEO check / broken links / missing titles, descriptions or alt text / `fimo site check` / is my site accessible / a11y or WCAG check / measure LCP or Web Vitals / why is the page slow / inspect network requests or console errors / Lighthouse score" → `references/site-checks.md`
|
|
104
|
-
- "Schedule a command / cron / nightly publish / recurring checks / `fimo schedules`" → `references/schedules.md`
|
|
105
|
-
- "Set env vars / configure API keys / add project secrets / local `.env.local` / `fimo vars` / `fimo secrets`" → `references/project-vars-and-secrets.md`
|
|
106
|
-
- "React to form submissions / publish changes / analytics reports / media activity / send events to Resend, Slack, GitHub, Zapier, or an HTTP endpoint / configure or debug outbound webhooks" → `references/webhooks.md`
|
|
107
|
-
- "Use a connected app / Google Search Console / clicks, impressions, rankings, keywords from Google / Google Analytics / GA4 users, sessions, traffic sources, key events / enable provider tools / integrations / add, inspect, search, or run an MCP server / `fimo integrations` or `fimo mcp`" → `references/integrations.md`
|
|
108
|
-
- "Firecrawl / scrape a public website / competitor research / agent web research" → `references/integrations.md` **+ load `references/integrations/firecrawl.md`**
|
|
109
|
-
- "Check credits / credit balance / can I keep using AI / billing credits / running low / how many credits are left" → `references/credits.md`
|
|
110
|
-
- "List history / create a restore point / recover content and code / restore a previous version / snapshot usage or retention" → `references/history.md`
|
|
111
|
-
- "Create a Branch / feature Branch / switch Branches / merge Branches / diff two Branches / Branch status / what changed on this Branch / sync from parent / cut a release / tag a version / go to prod" → `references/branches.md`
|
|
112
|
-
- "List my projects / clone an existing project locally / check out a project / delete this project / unpublish / rename the project / manage projects across the org" → `references/projects.md`
|
|
113
|
-
- "Migrate an existing Webflow / Framer / Squarespace / Wix / Carrd site from only a published URL" → load the `fimo-migration` skill, set the target up with `fimo migrate init <dir>`, and read the published site yourself with a browser — the CLI does not crawl it
|
|
114
|
-
- "Put my existing site or app on Fimo / link or deploy the app in this folder / host the site I built" → load the `fimo-migration` skill and follow its source-backed, same-framework path: `fimo link` keeps every word typed in the code, which Studio cannot edit, until the migration's content pass moves it to labels and the CMS
|
|
115
|
-
- "Migrate from an exported project, source repository, Webflow code export plus CMS CSVs, Framer CMS CSVs, Squarespace XML/CSV, Wix CSVs, Carrd/static export, or downloaded site files" → load the `fimo-migration` skill and use the source repo/export as the migration source of truth
|
|
116
|
-
- "How do AI agents read my site / markdown for agents" → `references/deploy.md`
|
|
117
|
-
- "Modify the URL of the website / change my project's address / connect a custom domain (e.g. blog.example.com) / rename the Fimo-provided `*.fimo.site` subdomain / buy a new domain through Fimo / set up a domain" → `references/domains.md`
|
|
118
|
-
- "Invite a collaborator / add Marc / share with client" → `references/invite.md`
|
|
119
|
-
- "Login / log out / who am I / switch organization" → `references/account.md` — note: switching **org** is `fimo orgs switch`; bare `fimo switch` changes the active **Fimo Branch** (see `references/branches.md`)
|
|
120
|
-
- "Install Fimo for my agent / fimo skills install / set up Claude Code, Codex, or Cursor for Fimo" → `references/agent-setup.md`
|
|
121
|
-
- "Refresh / update installed Fimo skills / fimo skills sync / agent missing the latest Fimo conventions" → `references/agent-setup.md`
|
|
122
|
-
- "Update / upgrade the project's fimo packages / move to a new Fimo release / `fimo update`" → `references/update.md`. Never edit `fimo` or `fimo-*` versions directly in `package.json`; `fimo update` keeps package pins and codemods aligned.
|
|
123
|
-
- "Report a Fimo problem or blocking feature request / contact Fimo support / a Fimo API or command keeps failing / a documented argument is rejected / a supported operation needs an undocumented workaround / a Fimo API is abnormally slow / a confirmed missing capability blocks completion or forces a fragile or heavily manual workaround" → `references/support.md`
|
|
124
|
-
- "Regenerate rule files / I edited AGENTS.md / fimo rules sync" → `references/agent-setup.md`
|
|
125
|
-
- "Show analytics / visitor stats / traffic / pageviews / how is my site performing / top pages / where do visitors come from" → `references/analytics.md` (7-day preview free for all; longer ranges require paid)
|
|
126
|
-
- "Mark a date on the analytics chart / annotate the chart with a deploy / add a launch note" → `references/analytics.md` § Annotations
|
|
127
|
-
|
|
128
|
-
## Lifecycle nudges
|
|
129
|
-
|
|
130
|
-
These fire at specific moments in the project lifecycle. **Surface them proactively** rather than waiting for the user to ask:
|
|
131
|
-
|
|
132
|
-
- **Right after `fimo init`** → `cd` into the new directory, read the project's `AGENTS.md` (or `CLAUDE.md` for Claude Code), run `fimo describe --json`, then load `fimo-code` and only the task/framework references it routes to. The rules file came into existence mid-session and may not be auto-loaded by the harness. See `references/init.md` § Load the project context.
|
|
133
|
-
- **When `fimo init` created or scaffolded a new site (create-new path, including a Studio-supplied `--project-id`)** → after init and context loading succeed, run the single first-preview deploy and return the preview and dashboard links — see `references/init.md` § Create the first hosted preview. That deploy is also the sandbox warm-up; never run a separate warm-up deploy. Skip it only if the user explicitly said not to deploy. Linking a project with existing code and migrations keep their own approval rules.
|
|
134
|
-
- **Right after `fimo init`** → suggest `fimo rename "<Display Name>"` to set a human-readable name (the default post-init name is an auto-generated slug). Infer the name from what the user is building (e.g. "Acme Coffee" for a café, "Jane Doe Portfolio" for a personal site). See `references/init.md`.
|
|
135
|
-
- **Right after `fimo init`** → start the app locally with the project's package-manager `dev` script (`pnpm dev` / `npm run dev` / `yarn dev` / `bun dev`) in the background. This localhost server with live reload is your iteration loop — edit, show, repeat. No deploy is needed to see local changes. If the initiating request did not say what to build, ask the developer — after the first preview on the create-new path, never as a blocker before initializing.
|
|
136
|
-
- **When a user-visible unit of work looks done outside first-time onboarding** → **offer** to deploy (`fimo deploy` for a hosted project preview, `fimo deploy --publish` to go live) and run it only after the developer confirms — or immediately if they ask. Never deploy ordinary edits on your own. See `references/deploy.md`.
|
|
137
|
-
- **Optional, outside new-project onboarding (its first preview already warms the sandbox), if you already know a deploy is coming** → warm the sandbox early with `fimo deploy -m "chore: init" &` in the background so the one-time ~15-30s provision + dep install happens while you work and the real deploy lands warm (~4-10s). This is a perf optimization, not a requirement. See `references/deploy.md` § Warm the sandbox early in a session.
|
|
138
|
-
- **You need the current preview URL but haven't changed code** (opening it, screenshotting it, handing it to another tool, the previous URL expired) → `fimo preview url`, never a no-op `fimo deploy`. See `references/preview.md`.
|
|
139
|
-
- **When the user wants to try something risky / explore a redesign without touching the live site** → suggest a feature Branch: `fimo checkout -b <name>` gives an isolated Branch + DB + preview. Deploy previews there, then `fimo merge` it back and `fimo publish`. See `references/branches.md`.
|
|
140
|
-
- **After completing or safely preserving the user's main work, when a confirmed Fimo platform failure still materially blocks the task after one safe recovery attempt, or a confirmed missing capability blocks completion or forces a fragile or heavily manual workaround** → use the built-in `supportReport` tool. Do not wait for the user to ask and do not stop after only describing the gap. See `references/support.md`.
|
|
141
|
-
- **After the first successful `fimo deploy`** → suggest `fimo invite` if the project involves multiple people. Typical roles: `edit` for developers/content editors, `view` or `comment` for clients/stakeholders, `full` for project leads. See `references/invite.md`.
|
|
142
|
-
- **After the automatic first-preview deploy on the create-new path, before the project has been published** → if there is no custom domain and the free default `*.fimo.site` slug still looks generated or was never explicitly chosen, offer to find a cleaner free subdomain. It needs no DNS. Never claim one without explicit user confirmation: suggest candidates, let the user choose, then rename it. Choosing the slug does not publish the site; the URL starts resolving only after the first successful `fimo deploy --publish`. Skip this nudge if the user already chose the default slug, attached a custom domain, or declined. See `references/domains.md` § Offer a cleaner default URL before first publish.
|
|
143
|
-
- **When the user wants to modify the URL of their website** → walk through `references/domains.md`. The CLI surface covers renaming the Fimo-provided subdomain (`fimo domains rename-default`, free), attaching a domain they already own (`fimo domains add`, Premium), and buying a new domain through Fimo (`fimo domains buy`, Premium).
|
|
144
|
-
|
|
145
|
-
## Anti-Patterns
|
|
146
|
-
|
|
147
|
-
- **Editing `.fimo/project.json`** — read-only; it's the link between local and remote site. Treat as a generated file.
|
|
148
|
-
- **Treating `fimo deploy` as the working loop or a required final step** — the loop is local (`pnpm dev` etc.). Deploy commits + pushes + round-trips the sandbox; it's for hosted previews / going live, on-demand. Iterate locally and deploy at logical breakpoints. See `references/deploy.md`.
|
|
149
|
-
- **Deploying without the developer asking or confirming** — new-project onboarding authorizes exactly one automatic first preview deploy (unless the user said not to deploy); every other deploy is offer-then-confirm. Don't auto-deploy after finishing an ordinary edit.
|
|
150
|
-
- **Running `fimo deploy` just to get the current preview URL** — that's a commit + push + sandbox sync when only destination resolution is needed. Use `fimo preview url` instead. See `references/preview.md`.
|
|
151
|
-
- **Using `fimo deploy --publish` casually** — `--publish` makes the site live to the public. Plain `fimo deploy` (preview) is the default. Use `--publish` only when the user says "ship it" / "go live" / "publish".
|
|
152
|
-
- **Bare `fimo init` in a non-interactive shell** — will hang. Always pass `[dir]`, `--no-install` (or `--install`), `--no-skills` (or `--skills`), and `--org`/`--agents` as needed explicitly when scripted.
|
|
153
|
-
- **Hardcoding content / strings / images in code, or committing image and video files** — that's what schemas, `t()`, and the media library are for. See the `fimo-code` skill's non-negotiable boundaries.
|
|
154
|
-
- **Adding another deploy tool**. Fimo handles deploys; don't bolt another platform on.
|
|
155
|
-
- **Committing secrets or storing API keys as public variables** — server-side keys use `fimo vars add --private`; Fimo-only credentials use `fimo secrets`; public browser-safe values use `fimo vars`. Local env files are ignored and must not become deploy inputs.
|
|
156
|
-
- **Hardcoding tokens in flags** — use the credentials written by `fimo login` (one file per backend at `~/.config/fimo/credentials/<host>-<hash>.json`).
|
|
157
|
-
- **Treating the daily allowance as extra credits** — the allowance section appears only for legacy Premium organizations, and `fimo credits` already includes its spendable credits in "Available now"; it is accounting context, not an amount to add.
|
|
158
|
-
- **Trying to refill credits from the CLI** — `fimo credits` is read-only. Buying/refilling credits belongs in the billing UI for now.
|
|
27
|
+
## Work loop
|
|
28
|
+
|
|
29
|
+
- Work locally: run the project's `dev` script in the background (`pnpm dev`, `npm run dev`, `yarn dev`, or `bun dev`, from the lockfile). Live reload shows each change. You do not need a deploy to see it.
|
|
30
|
+
- `fimo validate` runs all checks and codegen, and fails when default-locale labels are missing. It does not type check: also run the project's `typecheck` or `check` script. Keep `fimo validate --json` first in the `build` script.
|
|
31
|
+
- Keep editor content, copy, and media in schemas, labels, and the media library, not in code (`fimo-code`).
|
|
32
|
+
- Fimo hosts and deploys the site. Do not add another hosting or deploy tool.
|
|
33
|
+
|
|
34
|
+
## Safety
|
|
35
|
+
|
|
36
|
+
- **Deploy:** `fimo deploy -m "<message>"` makes a hosted preview. Deploy only when the developer asks or agrees. When a unit of work looks done, offer a deploy. The only automatic deploy is the first preview after `fimo init` creates a site (`--ref init`).
|
|
37
|
+
- **Publish:** add `--publish` only when the user says to publish, ship, or go live. It makes the site public.
|
|
38
|
+
- **Preview URL:** when you need the current preview URL and the code did not change, run `fimo preview url`. Never deploy only to get a URL.
|
|
39
|
+
- **Secrets:** put server-side keys in `fimo vars add <NAME> --private`, and Fimo-only credentials in `fimo secrets`. Never commit secrets, put them in public variables, or pass tokens in flags. `fimo login` stores the session.
|
|
40
|
+
- **Packages:** change `fimo` and `fimo-*` versions only with `fimo update <version>`, never in `package.json`.
|
|
41
|
+
- **Blockers:** first finish or save the main work. Then, if a confirmed Fimo platform failure still blocks the task after one safe recovery step, or a missing capability blocks it or forces a fragile workaround, use the `supportReport` tool. Do not wait for the user to ask (`--ref support`).
|
|
42
|
+
|
|
43
|
+
## Find the reference
|
|
44
|
+
|
|
45
|
+
Load a reference with `fimo skills get fimo-cli --ref <name>`. "+ fimo-code `<ref>`" means: also load that `fimo-code` reference and the reference for the detected framework.
|
|
46
|
+
|
|
47
|
+
- Create a site, link a project, `fimo init`, and the steps right after init → `init`
|
|
48
|
+
- No account or no browser: `fimo new <dir> --yes --json` (a person claims the site in 72 hours; `fimo claim --json` shows the link; `fimo new --instructions` prints the guide) → `account`
|
|
49
|
+
- Sign in, who am I, switch organization (`fimo orgs switch`; `fimo switch` changes the Branch) → `account`
|
|
50
|
+
- List, clone, rename, delete, or unpublish projects → `projects`
|
|
51
|
+
- Project snapshot: framework, schemas, routes, locales, tree (`fimo describe --json`) → `describe`
|
|
52
|
+
- Content types, Singles, entries, a blog, the CMS → `content` + fimo-code `content/schema`
|
|
53
|
+
- Page routes, params, and sources that Studio shows → `pages`
|
|
54
|
+
- Forms and form submissions → `forms` + fimo-code `forms`
|
|
55
|
+
- Upload, replace, or remove media files → `assets` + fimo-code `assets`
|
|
56
|
+
- Generate or edit an image or video with AI → `media` (+ fimo-code `assets` to show it in the UI)
|
|
57
|
+
- Labels, static copy, missing `t()` values → `labels` + fimo-code `labels`
|
|
58
|
+
- Locales and the default locale → `locales` + fimo-code `locales`
|
|
59
|
+
- Deploy, publish, a failed deploy or publication, blocked build scripts, markdown pages for AI agents → `deploy`
|
|
60
|
+
- Preview URL → `preview`
|
|
61
|
+
- Redirects, security headers, clean URLs, trailing slash → `hosting`
|
|
62
|
+
- Broken links, SEO, alt text, accessibility, Web Vitals, console errors in a browser → `site-checks`
|
|
63
|
+
- Branches: create, switch, status, diff, merge into `main`, pull. Suggest a Branch for a risky change (`fimo checkout -b <name>`) → `branches`
|
|
64
|
+
- Restore points and recovery → `history`
|
|
65
|
+
- Environment variables and secrets → `project-vars-and-secrets`
|
|
66
|
+
- Send form submissions, publishes, or other events to Slack, Resend, GitHub, Zapier, or a URL → `webhooks`
|
|
67
|
+
- Connected apps, Search Console, Google Analytics, MCP servers → `integrations`; Firecrawl web research → also `integrations/firecrawl`
|
|
68
|
+
- Visitors, page views, top pages, chart annotations → `analytics`
|
|
69
|
+
- Site URL: rename the free `*.fimo.site` slug (`fimo domains rename-default <slug>`), add a domain the user owns, buy a domain → `domains`
|
|
70
|
+
- Invite people. After the first deploy, suggest it when other people work on the site → `invite`
|
|
71
|
+
- AI credit balance (read-only) → `credits`
|
|
72
|
+
- Scheduled commands → `schedules`
|
|
73
|
+
- Set up an AI agent, install or sync Fimo skills, `fimo rules sync` → `agent-setup`
|
|
74
|
+
- Update Fimo packages → `update`
|
|
75
|
+
- Report a Fimo problem → `support`
|
|
76
|
+
- Move an existing site or app onto Fimo (published URL, source code, export, CSV files, `fimo link`) → load the `fimo-migration` skill
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: fimo-cli
|
|
3
|
+
description: >-
|
|
4
|
+
Operate a Fimo site through the `fimo` tool: content, Singles, schemas,
|
|
5
|
+
forms and their submissions, media and AI images, labels and locales, pages,
|
|
6
|
+
analytics, domains, webhooks, schedules, site checks and history. Read the
|
|
7
|
+
matching reference before the first command in a domain.
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Fimo CLI
|
|
11
|
+
|
|
12
|
+
The `fimo` tool runs each command for you, on this project's Fimo version and on the version of the site you are working on, and returns the CLI's JSON. Fimo serves the preview, so there is nothing to install, start or deploy. Code in the project (schema JSON, generated clients, primitives, framework adapters) is the `fimo-code` skill. For one command's flags, run it with `--help`.
|
|
13
|
+
|
|
14
|
+
## Every task
|
|
15
|
+
|
|
16
|
+
- **Site knowledge:** before planning, recommendations, design, copy, content, or code work, read `knowledge get`. Rules: reference `knowledge`.
|
|
17
|
+
- **Output:** read `data`. Branch on `error.code`, not on the message, and follow `hint`. Commands never prompt, so give each answer as a flag (`--yes`).
|
|
18
|
+
- **Content lives in Fimo:** editor content, copy and media go in schemas, labels and the media library, not in code, so people can change them in Studio without you (`fimo-code`).
|
|
19
|
+
|
|
20
|
+
## Find the reference
|
|
21
|
+
|
|
22
|
+
Load a reference with `skillLoad` (`fimo-cli`, reference `<name>`). "+ fimo-code `<ref>`" means: also load that `fimo-code` reference and the reference for the project's framework.
|
|
23
|
+
|
|
24
|
+
- Project snapshot: framework, schemas, routes, locales, tree (`describe`) → `describe`
|
|
25
|
+
- Content types, Singles, entries, a blog, the CMS → `content` + fimo-code `content/schema`
|
|
26
|
+
- Page routes, params, and the sources Studio shows for a page → `pages`
|
|
27
|
+
- Forms and form submissions → `forms` + fimo-code `forms`
|
|
28
|
+
- Upload, replace, or remove media files → `assets` + fimo-code `assets`
|
|
29
|
+
- Generate or edit an image or video with AI → `media` (+ fimo-code `assets` to show it on the site)
|
|
30
|
+
- Labels, static copy, missing `t()` values → `labels` + fimo-code `labels`
|
|
31
|
+
- Locales → `locales` + fimo-code `locales`
|
|
32
|
+
- Preview URL → `preview`; a preview that fails to build, and its logs → `deploy`
|
|
33
|
+
- Redirects, security headers, clean URLs, trailing slash → `hosting`
|
|
34
|
+
- Broken links, SEO, alt text, accessibility, Web Vitals, console errors in a browser → `site-checks`
|
|
35
|
+
- Restore points → `history`
|
|
36
|
+
- Send form submissions, publishes, or other events to Slack, Resend, GitHub, Zapier, or a URL → `webhooks`
|
|
37
|
+
- Firecrawl web research and Fal media → `integrations/firecrawl`, `integrations`
|
|
38
|
+
- Visitors, page views, top pages, chart annotations → `analytics`
|
|
39
|
+
- Site URL: the free `*.fimo.site` slug, a domain the person owns, buying a domain → `domains`
|
|
40
|
+
- Scheduled commands → `schedules`
|
|
41
|
+
- Report a Fimo problem → `support`
|
|
42
|
+
- Move an existing site or app onto Fimo → load the `fimo-migration` skill
|
|
@@ -1,126 +1,63 @@
|
|
|
1
|
-
# Branches
|
|
1
|
+
# Branches
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Branches are in beta: some commands and cross-surface merges can still fail.
|
|
4
4
|
|
|
5
|
-
A Fimo **Branch** is a
|
|
5
|
+
A Fimo **Branch** is a Git branch plus its own database, preview sandbox, preview URL, and asset prefix. The commands copy `git` verbs. An **Environment** in Project Settings (Production, Preview) is a policy that groups Branches; it is not a Branch.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
## Which Branch a command uses
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
```bash
|
|
14
|
-
fimo --branch <name> <command> # peek at another Branch for one command (does not switch)
|
|
15
|
-
```
|
|
16
|
-
|
|
17
|
-
- **`--branch <name>`** is the canonical global override. `fimo --branch main status` inspects `main` while you stay checked out on your feature Branch.
|
|
18
|
-
- **`--env <name>`** is not a Branch selector. It is rejected; use `--branch <name>`.
|
|
19
|
-
- Git-changing commands use the current branch; cross-branch status only reports the mismatch.
|
|
20
|
-
- If Git cannot name a Branch, the CLI stops instead of guessing. Check out a Branch or pass `--branch <name>`. Sandboxes receive their Branch through `FIMO_ENV`.
|
|
21
|
-
- If the git branch maps to no Fimo Branch, the CLI errors with a hint (`fimo branch` to list, `fimo branch <name>` to create) rather than guessing.
|
|
22
|
-
- The project's default Branch cannot be deleted. Existing standalone projects use **`main`**.
|
|
23
|
-
- **`release/*`** Branches are **read-only** — they're tags produced by `fimo publish`, not branches you push to. `fimo deploy` refuses them.
|
|
24
|
-
- **`prod`** is protected: it cannot be created, forked from, checked out, or deleted. It's updated by publishing, never by pushing.
|
|
9
|
+
- A site command uses the Fimo Branch that matches the current Git branch, and prints its name.
|
|
10
|
+
- `fimo --branch <name> <command>` reads or writes another Branch for one command, without a switch. `--env` is not accepted. `deploy` and `pull` change Git, so they need the matching checkout: run `fimo checkout <name>` first.
|
|
11
|
+
- If Git names no branch (detached HEAD) and you pass no `--branch`, or the Git branch has no Fimo Branch, the CLI stops with a hint. It does not guess.
|
|
12
|
+
- **Protected:** the default Branch (`main`) cannot be deleted. A checkout of a `release/*` tag is read-only. `prod` cannot be created, forked, checked out, or deleted; only a publish changes it.
|
|
25
13
|
|
|
26
14
|
## Commands
|
|
27
15
|
|
|
28
|
-
| Command | git analogue | What it does |
|
|
29
|
-
| ----------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
30
|
-
| `fimo branch` | `git branch` | List Branches (current marked `*`). `-v` includes deleted Branches. |
|
|
31
|
-
| `fimo branch <name>` | `git branch <name>` | Create a Branch off the current one. `--from <branch>` forks from a different parent. Provisions DB + sandbox + preview + R2 prefix. |
|
|
32
|
-
| `fimo branch -d <name>` | `git branch -d` | Delete a Branch — tears down its sandbox, Neon branch, and R2 prefix. Refuses `main` and `prod`. |
|
|
33
|
-
| `fimo checkout <name>` | `git checkout` | Switch to a Branch (checks out the matching git branch; the app derives its Branch from that branch at startup). `-b` creates + switches; `--from <branch>` sets the parent. |
|
|
34
|
-
| `fimo switch <name>` | `git switch` | Switch to an existing Branch. Takes only `<name>` (no `-b`/`--from`) — use `fimo checkout -b` to create + switch. |
|
|
35
|
-
| `fimo pull` | `git pull` | Fast-forward the local checkout to the Branch's latest code on Fimo. Never changes the Branch on the server. |
|
|
36
|
-
| `fimo diff [from] [to]` | `git diff` | Two-Branch diff across all surfaces. Defaults `from` = current Branch, `to` = `main`. `--surface <name>` limits to one; `--json`; `--no-color`. |
|
|
37
|
-
| `fimo status` | `git status` | Multi-surface status for the current Branch vs its parent. See below. |
|
|
38
|
-
| `fimo merge <from>` | `git merge` | Merge another Branch into the current one (multi-surface, atomic, interactive conflict resolver). See below. |
|
|
39
|
-
| `fimo publish` | — | Publish the revision already on the Fimo remote (no push) with a stable Fimo publication ID. See "Publishing" below. |
|
|
40
|
-
|
|
41
|
-
All of these accept the global `--branch` override. `diff`, `status`, `merge`, and `publish` additionally accept `-C, --cwd <dir>` to point at a project directory.
|
|
42
|
-
|
|
43
|
-
> **`fimo switch` changes the active Fimo Branch, not the org.** A Fimo Branch keeps its code, database, sandbox, content, and preview together. To change your active organization, use `fimo orgs switch` — see `references/account.md`.
|
|
44
|
-
|
|
45
|
-
## The 6 surfaces
|
|
46
|
-
|
|
47
|
-
`status`, `diff`, and `merge` all reason over the same per-Branch surfaces, in this order:
|
|
48
|
-
|
|
49
|
-
`code` · `schemas` · `content` · `translations` · `assets` · `forms`
|
|
50
|
-
|
|
51
|
-
`--surface <name>` on `diff` and the per-surface flags on `status` (`--code`, `--content`, `--i18n`, `--agents`, `--assets`, `--forms`) filter to one of them.
|
|
52
|
-
|
|
53
|
-
## Typical PR-style flow
|
|
54
|
-
|
|
55
|
-
```bash
|
|
56
|
-
fimo checkout -b feat/seo # branch off main: git branch + Branch provisioned
|
|
57
|
-
# …generate / edit code, schemas, content, translations…
|
|
58
|
-
fimo deploy -m "feat: seo pass" # deploy a preview of the feat/seo Branch
|
|
59
|
-
fimo preview url # canonical URL to open / screenshot the feat/seo preview
|
|
60
|
-
fimo status # see what changed vs main, surface by surface
|
|
61
|
-
fimo checkout main # back to main
|
|
62
|
-
fimo merge feat/seo # merge the Branch back into main (resolve conflicts)
|
|
63
|
-
fimo publish --label "Homepage launch" --notes "Initial production publish"
|
|
64
|
-
fimo branch -d feat/seo # tear down the feature Branch
|
|
65
|
-
```
|
|
66
|
-
|
|
67
|
-
## `fimo status`
|
|
68
|
-
|
|
69
|
-
The showcase command — a unified, color-coded report of what's changed on the current Branch, grouped by surface, with per-surface counts.
|
|
70
|
-
|
|
71
16
|
```bash
|
|
72
|
-
fimo
|
|
73
|
-
fimo
|
|
74
|
-
fimo
|
|
75
|
-
fimo
|
|
76
|
-
fimo
|
|
17
|
+
fimo branch [-v] [--all] # list (-v: deleted too; --all: agent task/* Branches too)
|
|
18
|
+
fimo checkout -b <name> [--from <branch>] # create a Branch from the current one (or --from) and switch to it
|
|
19
|
+
fimo checkout <name> # switch; `fimo switch <name>` is the same (no -b)
|
|
20
|
+
fimo branch <name> [--from <branch>] # create without a switch
|
|
21
|
+
fimo branch -d <name> # delete: removes its sandbox, database, and assets
|
|
22
|
+
fimo status [--vs <branch>] [--short] [--code|--content|--i18n|--assets|--forms] --json
|
|
23
|
+
fimo diff [from] [to] [--surface <name>] --json # from = current Branch, to = its parent (else main)
|
|
24
|
+
fimo merge <from> [-y] [--resume] [--allow-direct-merge] --json
|
|
25
|
+
fimo pull # fast-forward this checkout to the Branch on Fimo
|
|
77
26
|
```
|
|
78
27
|
|
|
79
|
-
-
|
|
80
|
-
-
|
|
28
|
+
- **Create Branches with `fimo`, not `git checkout -b`.** Raw Git makes no database, sandbox, or preview. If that happened, run `fimo branch <name> --from <parent>` to add them.
|
|
29
|
+
- `fimo switch` changes the Branch. `fimo orgs switch` changes the organization.
|
|
30
|
+
- `status`, `diff`, and `merge` compare six surfaces: `code`, `schemas`, `content`, `translations`, `assets`, `forms`. `status` also shows uncommitted local edits. A slow surface shows as timed out: treat it as unknown, not unchanged.
|
|
31
|
+
- Code reads its Fimo connection from the Git branch and `.fimo/project.json`. Do not hardcode the tenant API URL; an explicit host variable overrides that on every Branch.
|
|
32
|
+
- Deleting a Branch removes its data. Delete only a Branch that the user no longer needs.
|
|
81
33
|
|
|
82
|
-
##
|
|
34
|
+
## Typical flow
|
|
83
35
|
|
|
84
36
|
```bash
|
|
85
|
-
fimo
|
|
86
|
-
fimo
|
|
87
|
-
fimo
|
|
88
|
-
fimo
|
|
37
|
+
fimo checkout -b feat/seo --from main # isolated Branch from main
|
|
38
|
+
fimo deploy -m "feat: seo pass" # hosted preview of feat/seo
|
|
39
|
+
fimo preview url # its preview URL
|
|
40
|
+
fimo status # what changed, surface by surface
|
|
41
|
+
fimo checkout main
|
|
42
|
+
fimo merge feat/seo --allow-direct-merge # only when the user asked to merge into main
|
|
43
|
+
fimo deploy --publish # only when the user says to go live (--ref deploy)
|
|
44
|
+
fimo branch -d feat/seo
|
|
89
45
|
```
|
|
90
46
|
|
|
91
|
-
|
|
92
|
-
- On conflicts nothing is applied. In a terminal you get a resolver per row: **parent** (keep the target's value), **child** (take the source's value), **pick** (edit in `$EDITOR`), or **abort**. `-y` keeps the target's value for everything.
|
|
93
|
-
- `--json` never prompts. Unresolved conflicts exit non-zero with `MERGE_CONFLICTS`; `error.details` carries `merge_id`, `from`, `to`, and `conflicts`. Re-run with `--resume --yes` to keep the target's values, or resolve interactively.
|
|
94
|
-
- After resolutions are accepted the CLI waits for the merge: success is `status: "ok"` with the completed merge's `mergeId` and `summary` but no `applied` list (per-surface counts are only reported when a merge applies cleanly without conflicts); `MERGE_FAILED` and `MERGE_CANCELLED` are terminal; `MERGE_IN_PROGRESS` means it is still applying — run `--resume` to keep following it. `--resume` never resubmits a merge that is already applying.
|
|
95
|
-
|
|
96
|
-
## `fimo pull`
|
|
97
|
-
|
|
98
|
-
Brings the current Branch's latest code from Fimo into the local checkout, like `git pull --ff-only fimo <branch>`. Run it before editing locally when the Branch may have changed elsewhere (Studio, an agent, a teammate's deploy). It only reads from Fimo: it never changes the Branch on the server. To bring `main` into a feature Branch, use `fimo merge main`.
|
|
99
|
-
|
|
100
|
-
It never rebases, merges, or stashes local work. It stops instead:
|
|
101
|
-
|
|
102
|
-
- `ENV_BRANCH_BEHIND_DIRTY` — the checkout is behind and has uncommitted changes. Commit or stash them, then run `fimo pull` again.
|
|
103
|
-
- `ENV_BRANCH_DIVERGED` — local commits and remote commits both exist. Run `git pull --rebase fimo <branch>`, fix any conflicts, then `fimo deploy`.
|
|
104
|
-
- `ENV_BRANCH_MISMATCH` — the git checkout is on another branch, or a detached HEAD. Run `fimo checkout <branch>`.
|
|
105
|
-
|
|
106
|
-
`--json` returns `details.commits_pulled` and `details.head` (the checkout's commit afterwards).
|
|
107
|
-
|
|
108
|
-
## Publishing — `fimo publish` vs `fimo deploy --publish`
|
|
47
|
+
## Merge
|
|
109
48
|
|
|
110
|
-
|
|
49
|
+
- **`fimo merge` into `main` stops with `PROTECTED_FLOW`** unless you add `--allow-direct-merge`. Add it only when the user asked to merge into `main`. Merges between other Branches need no flag.
|
|
50
|
+
- A merge with conflicts applies nothing. A terminal shows a resolver per conflict: keep the target (current Branch) value, take the source value, edit the value, or stop. `-y` keeps the target value for every conflict.
|
|
51
|
+
- `--json` never prompts. Conflicts exit with `MERGE_CONFLICTS`; `error.details` has `merge_id`, `from`, `to`, and `conflicts`. To keep the target values, run `fimo merge <from> --resume --yes`.
|
|
52
|
+
- After the answers are accepted, the CLI waits for the merge. Success is `status: "ok"` with the `mergeId`; per-surface counts (`applied`) appear only for a merge with no conflicts, so their absence is not a reason to retry. `MERGE_FAILED` and `MERGE_CANCELLED` are final. `MERGE_IN_PROGRESS` means it still applies: run `--resume` to follow it. `--resume` on a merge that still applies only follows it; it does not send it again.
|
|
53
|
+
- To bring `main` into a feature Branch, run `fimo merge main` on the feature Branch.
|
|
111
54
|
|
|
112
|
-
|
|
113
|
-
- **`fimo deploy --publish`** — pushes the current Production source Branch and flips the project live. See `references/deploy.md`.
|
|
55
|
+
## Pull
|
|
114
56
|
|
|
115
|
-
|
|
57
|
+
`fimo pull` gets the Branch's latest code from Fimo, like `git pull --ff-only fimo <branch>`. Run it before you edit when Studio, an agent, or a teammate may have changed the Branch. It never changes the Branch on Fimo, and it never rebases, merges, or stashes:
|
|
116
58
|
|
|
117
|
-
|
|
59
|
+
- `ENV_BRANCH_BEHIND_DIRTY`: commit or stash the local changes, then pull again.
|
|
60
|
+
- `ENV_BRANCH_DIVERGED`: run `git pull --rebase fimo <branch>`, fix conflicts, then `fimo deploy`. Never force-push.
|
|
61
|
+
- `ENV_BRANCH_MISMATCH`: Git is on another branch or a detached HEAD. Run `fimo checkout <branch>`.
|
|
118
62
|
|
|
119
|
-
|
|
120
|
-
- **Hardcoding the tenant API URL** — the framework runtime derives it from the
|
|
121
|
-
git branch and `.fimo/project.json`. Use an explicit host variable only as a
|
|
122
|
-
deliberate override, such as a local API; it then wins over derivation on
|
|
123
|
-
every branch.
|
|
124
|
-
- **Trying to push to or delete `prod` / `release/*`** — these are read-only/protected. Publish to update prod; never push.
|
|
125
|
-
- **`fimo merge` straight onto `main` as a habit** — it's gated for a reason. Merge on a branch, then publish.
|
|
126
|
-
- **Confusing `fimo switch` (Branch) with `fimo orgs switch` (org).**
|
|
63
|
+
`--json` returns `details.commits_pulled` and `details.head`.
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Bulk entry writes
|
|
2
|
+
|
|
3
|
+
Load this page to create, update, or delete many entries in one command, or to write entries from a JSON file. Bulk writes use the same validation, locale, reference, and content-change paths as single writes.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
fimo entries bulk-create <Type> (--body '<json-array>' | --file <path> | --stdin) [--upsert-by <field>]
|
|
7
|
+
fimo entries bulk-update <Type> (--ids <id1>,<id2> | --where '<json>') --body '<json>' [--locale <code>]
|
|
8
|
+
fimo entries bulk-update <Type> (--file <path> | --stdin) [--locale <code>] # file shape: bulk-update --help
|
|
9
|
+
fimo entries bulk-delete <Type> (--ids <id1>,<id2> | --where '<json>') [--locale <code>]
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
## Create
|
|
13
|
+
|
|
14
|
+
`bulk-create` takes an array of normal create bodies. `--body`, `--file`, and `--stdin` all take the same array:
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
fimo entries bulk-create BlogPost --body '[{"data":{"title":"First"}},{"data":{"title":"Second"},"locale":"es"}]'
|
|
18
|
+
fimo entries bulk-create BlogPost --file posts.json
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## Same change for many entries
|
|
22
|
+
|
|
23
|
+
`--body` is a normal update body. Select the entries with `--ids`, or with a `--where` filter (the `entries list` filter, `--ref content/entries`):
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
fimo entries bulk-update BlogPost --ids <id1>,<id2> --body '{"data":{"status":"published"}}'
|
|
27
|
+
fimo entries bulk-update BlogPost --where '{"status":"draft"}' --body '{"data":{"status":"published"}}'
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## A different change for each entry
|
|
31
|
+
|
|
32
|
+
Write the per-entry array that `fimo entries bulk-update --help` shows to a file, then run it without `--body`:
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
fimo entries bulk-update BlogPost --file updates.json
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## Delete
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
fimo entries bulk-delete BlogPost --ids <id1>,<id2>
|
|
42
|
+
fimo entries bulk-delete BlogPost --where '{"archived":true}'
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## Results and limits
|
|
46
|
+
|
|
47
|
+
- Requested IDs that do not exist do not stop the valid writes: the CLI prints a warning, and `--json` lists the IDs in `warnings` and in `data.meta.missing`.
|
|
48
|
+
- Each `bulk-create` or `bulk-update` request saves all of its entries or none. `bulk-create` sends 100 entries per request (`--chunk-size`, at most 1,000). When a later request fails, the earlier ones stay saved: retry with `--upsert-by <field>` so that saved entries are updated, not created again.
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
# Read and filter entries
|
|
2
|
+
|
|
3
|
+
Load this page to filter, sort, search, select fields, or populate references and media. Write commands are in `--ref content`.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
fimo entries list <Type> [--where <json>] [--sort [-]<field>] [--search <q>] [--fields <a,b>] [--populate <a,b>]
|
|
7
|
+
[--locale <code>] [--limit <n>=20] [--cursor <cursor>] [--all-pages]
|
|
8
|
+
fimo entries get <Type> <id> [--locale <code>] [--populate <a,b>]
|
|
9
|
+
fimo singles get <Type> [--locale <code>] [--populate <a,b>]
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
fimo entries list BlogPost --where '{"featured":true}' --sort -publishedAt
|
|
14
|
+
fimo entries list BlogPost --where '{"rank":{"$gte":3}}' --sort rank
|
|
15
|
+
fimo entries list BlogPost --where '{"__fimo":{"contentType":{"$eq":"BlogPost"}}}'
|
|
16
|
+
fimo entries list BlogPost --search "launch"
|
|
17
|
+
fimo entries list BlogPost --limit 10 --cursor <next-cursor> --sort title
|
|
18
|
+
fimo entries list BlogPost --fields slug,title,excerpt,coverImage --sort -publishedAt --limit 12
|
|
19
|
+
fimo entries list BlogPost --fields slug,title,author --populate author
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## `--where`
|
|
23
|
+
|
|
24
|
+
- A JSON object keyed by schema field name. A plain value means equality and keeps its JSON type: `{"featured":true}`, `{"category":"react"}`.
|
|
25
|
+
- Operators: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$contains`, `$startsWith`, `$null`, as the field type allows.
|
|
26
|
+
- Fimo metadata is under `__fimo`. Only `__fimo.contentType` is filterable.
|
|
27
|
+
- A reference filter takes the target `id`: `{"author":"750e..."}`. On a to-many field, `$eq` and `$contains` mean "contains this target", `$in` means "contains any of these", `$ne` and `$nin` mean "contains none of these", and `$null: true` means empty or missing.
|
|
28
|
+
- You cannot filter polymorphic references yet: the command fails with a clear error.
|
|
29
|
+
|
|
30
|
+
## `--sort`, `--fields`, `--search`, pages
|
|
31
|
+
|
|
32
|
+
- `--sort field` is ascending and `--sort -field` is descending. You cannot sort on reference fields.
|
|
33
|
+
- `--fields` is a comma-separated list for list payloads. The API always returns `id`, `entryId`, `documentId`, and `locale`; name only the other fields the view needs.
|
|
34
|
+
- Use `--limit`, `--cursor` (the `nextCursor` of the last page), and `--all-pages` for pages. `--offset` still works in old scripts.
|
|
35
|
+
|
|
36
|
+
## `--populate`
|
|
37
|
+
|
|
38
|
+
- A comma-separated list of top-level reference, media, or blocks fields to embed. A blocks field populates every media value inside it. Nested paths such as `sections.image` and other field types return 400. Run `fimo schemas get <Type> --json` to see field names and types.
|
|
39
|
+
- Without `--populate`, a reference returns `{ "id": "..." }` and media returns the stored `{ "source", "id", "url", "alt" }`. With `--populate author,cover`, `author` returns the target entry in the requested locale, and `cover` also gets the current `name`, `mime`, `width`, and `height` of the asset.
|
|
40
|
+
- Populate does not choose which target fields return.
|
|
41
|
+
- A populated target that does not exist in the requested locale is `null`. Add `localeFallbacks=true` to get the best available locale variant instead; its `locale` field shows which one.
|
|
42
|
+
- Limits: 200 references in one to-many write, and 500 different populated documents per field in one request. Over a limit, the API returns 400.
|
|
43
|
+
|
|
44
|
+
## Reference values
|
|
45
|
+
|
|
46
|
+
- A fixed reference field has `"target": "Author"`; add `"many": true` for to-many. Write it as `{"id":"<id>"}`, or an array of those. Use `null` or `[]` for empty.
|
|
47
|
+
- A polymorphic reference has `"targets": ["Post", "Product"]` (never both `target` and `targets`). Write it as `{"contentType":"Post","id":"<id>"}`. Populated values are full entries of mixed types, and generated hooks add `$type` to each one.
|
|
48
|
+
- References inside blocks use the same write shapes (`id`, `documentId`, or `slug` selectors), but you cannot populate or filter them.
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
fimo entries create BlogPost --body '{"data":{"slug":"hello","title":"Hello","author":{"id":"750e8400-e29b-41d4-a716-446655440000"},"contributors":[]}}'
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
In generated app code, the same query uses `populate: ['author', 'contributors'] as const`. Let the generated client infer the result type. If you need a named type, use `BlogPostResult<TFields, TPopulate>` (fimo-code `content/clients`); writes use `BlogPostInput`.
|