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
|
@@ -1,142 +1,51 @@
|
|
|
1
|
-
# Deploy
|
|
1
|
+
# Deploy and publish
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
> **Local vs hosted.** The local dev server is localhost only. The Fimo **dashboard preview** and the authenticated **project-member preview URL** are served by the deployed sandbox — so if the developer wants to see the site in the dashboard or send another project member a link, that requires a `fimo deploy`.
|
|
6
|
-
|
|
7
|
-
`fimo deploy` uses the current Branch. New sites start on `main`; `release/*` is read-only, and `--publish` only runs from the project's configured Production source Branch. See `references/branches.md` for the multi-Branch workflow.
|
|
8
|
-
|
|
9
|
-
Before deploying, Fimo fast-forwards a clean checkout that is behind and stops on dirty-behind or diverged branches. This syncs the whole branch, including config commits from Studio or locale commands.
|
|
10
|
-
|
|
11
|
-
> **Just need the current preview URL?** That's `fimo preview url` — no commit or push. It waits if the hosted generation is still building. See `references/preview.md`.
|
|
12
|
-
|
|
13
|
-
## Commands
|
|
14
|
-
|
|
15
|
-
```bash
|
|
16
|
-
fimo deploy # preview only (default; reversible)
|
|
17
|
-
fimo deploy -m "<commit message>" # commit pending + push + sandbox sync
|
|
18
|
-
fimo deploy -m "<commit message>" --publish # also publish a new live version
|
|
19
|
-
```
|
|
20
|
-
|
|
21
|
-
- **`fimo deploy`** — commits pending changes, pushes to the current Branch, syncs that Branch's preview sandbox, and links to Fimo Studio.
|
|
22
|
-
- **`fimo deploy --publish`** — same as above, then triggers a live publish and prints the live URL. Runs from the configured Production source Branch only. **Only use `--publish` when the user signals "ship it"** — first-time site completion, or an explicit "publish" / "go live" request. Otherwise stick to plain `fimo deploy`. (For a _versioned_ prod release, use `fimo publish` instead — see below.)
|
|
23
|
-
- **`-m`** is the commit message used when there are uncommitted local changes; required in non-interactive shells. Omit if the working tree is already clean.
|
|
24
|
-
- **`--description "<why>"`** — the commit body for those changes: why they were made. Teammates and agents that later edit the same files read it, for example when a merge conflicts. Pass it with `-m` when the reason is not obvious from the diff.
|
|
25
|
-
|
|
26
|
-
## Reading deploy destinations
|
|
27
|
-
|
|
28
|
-
Interactive output uses named links. Agents and scripts should request JSON:
|
|
29
|
-
|
|
30
|
-
```bash
|
|
31
|
-
fimo deploy -m "<commit message>" --json
|
|
32
|
-
fimo deploy -m "<commit message>" --publish --json
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
Read these fields from `data`:
|
|
36
|
-
|
|
37
|
-
| Field | Destination |
|
|
38
|
-
| --------------- | ---------------------------------------------------------- |
|
|
39
|
-
| `studio_url` | Stable Fimo Studio project and Branch page. |
|
|
40
|
-
| `dashboard_url` | Deprecated compatibility alias for `studio_url`. |
|
|
41
|
-
| `app_url` | Public live site, returned after a successful `--publish`. |
|
|
42
|
-
|
|
43
|
-
When reporting the result, give the user `studio_url`. If a person or tool needs the hosted site itself, run `fimo preview url` after deploy.
|
|
44
|
-
|
|
45
|
-
Public variables are injected into preview, build, and deploy runtimes. Private variables (`fimo vars add --private`) reach the site's server code at runtime in previews and production, never an env file or the browser bundle. Secrets are not injected into the site; agents request them separately through their own config. See `references/project-vars-and-secrets.md`.
|
|
46
|
-
|
|
47
|
-
## Diagnose a failed publication
|
|
48
|
-
|
|
49
|
-
Use the publication ID returned by the failed command: run `fimo publish inspect <id> --json` for its durable status, then `fimo publish logs <id> --json` for a bounded build-log tail. Use `fimo publish list --cursor <cursor>` to continue through older attempts or `--all-pages` to fetch the complete retained history. `--before` remains a compatibility alias. Logs come from the hosting provider and may be unavailable after its deployment is reclaimed.
|
|
50
|
-
|
|
51
|
-
## Diagnose a failed preview deploy
|
|
52
|
-
|
|
53
|
-
A failed `fimo deploy --json` names the cause in `error.details.failure_code` and the phase in `error.details.phase`: `pull` (Git synchronization into the sandbox), `install` (dependency install), `restart` (dev-server start), or `readiness` (the final preview check); `acquire` and `sync-env` are the sandbox and environment steps before them. When the failed process produced output, the same error carries `error.details.exit_code` and a bounded, redacted `error.details.log_tail` (newest line last). Read that tail first: it is the failed process's own output, and a replacement sandbox that failed is discarded, so `fimo logs` shows the preview that is still serving rather than the attempt that failed. The top-level codes remain compatible:
|
|
54
|
-
|
|
55
|
-
- `SANDBOX_SYNC_FAILED` — the revision never became ready. Fix what the tail reports (a manifest or lockfile for `install`, the Git state for `pull`), then deploy again. When `error.details.failure_code` is `install_policy_blocked`, follow the typed repair in `error.details.repair`.
|
|
56
|
-
- `PREVIEW_NOT_READY` — the revision landed and the preview never proved ready. `error.message` names what the readiness probe last saw: a dev server that died, or the optimized dependency the public preview route was still delivering and what the dev server said about it over loopback. Fix what the tail reports; when there is no tail, act on the message before reading `fimo logs --json`, which shows a dev server that may be healthy.
|
|
57
|
-
|
|
58
|
-
`--no-wait` skips only the final readiness check. Pull, install, and dev-server failures are still reported with the same fields.
|
|
59
|
-
|
|
60
|
-
When there is no tail, run `fimo logs --json` before retrying. Read the newest install and dev-server events first; when the response is truncated, use its `previousCursor` as `fimo logs --cursor <cursor> --json` to fetch the preceding page, or use `--all-pages` to fetch every retained page. `--before` remains a compatibility alias. Do not recreate or replace the sandbox before collecting logs, because that can discard the failure evidence.
|
|
61
|
-
|
|
62
|
-
When Preview reports blocked dependency build scripts, treat that as a project security-policy repair, not a transient sandbox failure. Review every named package before approving it, then use the package manager's narrow project-owned mechanism:
|
|
63
|
-
|
|
64
|
-
- **pnpm:** add each approved package to `allowBuilds` in `pnpm-workspace.yaml`.
|
|
65
|
-
- **Yarn:** set `dependenciesMeta.<package>.built` in `package.json` for each approved package.
|
|
66
|
-
- **Bun:** add approved packages to `trustedDependencies` in `package.json`, or run the exact `bun pm trust <packages>` command Preview reports.
|
|
67
|
-
- **npm:** npm has no equivalent per-package approval error. Diagnose the failing lifecycle script itself; do not turn a generic npm script failure into a trust-policy change.
|
|
68
|
-
|
|
69
|
-
Run the same plain install locally and commit the policy plus lockfile before retrying Preview. Never bypass the error with `dangerouslyAllowAllBuilds`, `enableScripts`, or another global allow-all switch: Preview and publishing intentionally consume the committed project policy.
|
|
70
|
-
|
|
71
|
-
## Framework hosting
|
|
72
|
-
|
|
73
|
-
Fimo preview resolves `runtime.commands` override → package script → detected
|
|
74
|
-
framework default. Production uses `.fimo/config.json#runtime.framework` and
|
|
75
|
-
the same bounded build/install overrides. Existing applications keep their
|
|
76
|
-
router and hosting behavior: do not replace the router or derive
|
|
77
|
-
deployment rewrites from `.fimo/config.json#routes`. When setup changes are
|
|
78
|
-
needed, load the `fimo-code` skill's framework reference:
|
|
79
|
-
`references/frameworks/hosting.md` covers the React Router `fimoPreset()`
|
|
80
|
-
connector and the explicit catch-all used only by plain Vite `BrowserRouter`
|
|
81
|
-
SPAs; Astro's `fimo()` integration lives in `references/frameworks/astro.md`.
|
|
82
|
-
|
|
83
|
-
Redirects, response headers, and URL shape belong in
|
|
84
|
-
`.fimo/config.json#hosting` — see `references/hosting.md`.
|
|
85
|
-
|
|
86
|
-
## Warm the sandbox early in a session (optional)
|
|
87
|
-
|
|
88
|
-
This is a **performance optimization, only worth doing when you already know a deploy is coming** (the developer asked to publish, or you're confident they'll want a hosted preview soon). If you're just iterating locally, skip it — don't deploy pre-emptively. New-project onboarding never needs it: its automatic first preview deploy is the warm-up.
|
|
89
|
-
|
|
90
|
-
The first deploy of a project's life pays a one-time cost: the sandbox has to provision (create the VM, install the user's deps if they differ from the template's baked ones, start the dev server) — about 15-30s. Every deploy after that lands on a warm sandbox (~4-10s).
|
|
91
|
-
|
|
92
|
-
**To hide that one-time cost, kick off an early deploy in the background while you keep working.** The provisioning happens during your generation work, so by the time the developer wants a hosted preview, the sandbox is already warm and the deploy is fast.
|
|
3
|
+
`fimo deploy` is a milestone command, not the work loop. Work locally with the `dev` script. Deploy when the user wants a hosted preview, a link for a project member, the Studio preview, or to go live. The new-site first preview is the only automatic deploy (`--ref init`).
|
|
93
4
|
|
|
94
5
|
```bash
|
|
95
|
-
fimo deploy -m "
|
|
6
|
+
fimo deploy -m "<commit message>" [--description "<why>"] --json # hosted preview of the current Branch
|
|
7
|
+
fimo deploy -m "<commit message>" --publish --json # preview, then publish: the site goes live
|
|
8
|
+
fimo publish [--label <text>] [--notes <md>] --json # publish the revision already on Fimo, no push
|
|
9
|
+
fimo preview url --json # current hosted preview URL, no deploy
|
|
96
10
|
```
|
|
97
11
|
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
## Publishing: `fimo deploy --publish` vs `fimo publish`
|
|
12
|
+
## What a deploy does
|
|
101
13
|
|
|
102
|
-
|
|
14
|
+
- It commits pending changes (`-m` is the subject, `--description` is the body: why the change was made), pushes to the current Branch, and syncs that Branch's preview sandbox (it installs and restarts when needed). Batch related edits into one deploy.
|
|
15
|
+
- It uses the Branch of the current Git checkout. A checkout of a `release/*` tag is read-only. `--publish` and `fimo publish` run only from the configured production source Branch (default `main`). Other Branches: `--ref branches`.
|
|
16
|
+
- Before it changes files, it fast-forwards a clean checkout that is behind. It stops on a dirty checkout that is behind, or on a diverged one: follow the `hint`. If the push still loses a race, run `git pull --rebase fimo <branch>`, fix conflicts, and deploy again.
|
|
17
|
+
- Read `data.studio_url` and give it to the user (`data.dashboard_url` is an old alias). After `--publish`, `data.app_url` is the public site. For the hosted preview URL, run `fimo preview url`.
|
|
18
|
+
- Public variables reach preview and production. Private variables reach server code and the build, never the `.env` file; do not read them in browser code. Secrets do not reach the site (`--ref project-vars-and-secrets`).
|
|
103
19
|
|
|
104
|
-
|
|
20
|
+
## Publish safely
|
|
105
21
|
|
|
106
|
-
|
|
22
|
+
- **Publish only when the user says to publish, ship, or go live.** Publishing makes the site public.
|
|
23
|
+
- Local changes to go live: `fimo deploy --publish`. The revision already on Fimo is the release: `fimo publish` (it never pushes).
|
|
24
|
+
- Check the reported source commit and warnings before you report success. If local work is not in the build, or the built commit is unknown, follow the hint.
|
|
25
|
+
- A failed publication usually gives its id (`error.details.publication_id`; else find it with `fimo publish list`). Run `fimo publish inspect <id> --json` for the status and cause, then `fimo publish logs <id> --json` for the build log. The hosting provider can delete old logs: then report that, and do not publish again only to get logs. Older attempts: `fimo publish list --cursor <cursor>` or `--all-pages`.
|
|
107
26
|
|
|
108
|
-
|
|
27
|
+
## A failed preview deploy
|
|
109
28
|
|
|
110
|
-
-
|
|
111
|
-
-
|
|
29
|
+
- When known, the error names the step in `error.details.phase` (`acquire`, `pull`, `sync-env`, `install`, `restart`, `readiness`) and the cause in `error.details.failure_code`, with `error.details.exit_code` and `error.details.log_tail` (newest line last) when the process wrote output. **Read the tail first.** A failed replacement sandbox is deleted, so `fimo logs` shows the preview that still serves, not the failed attempt.
|
|
30
|
+
- `SANDBOX_SYNC_FAILED`: the revision never became ready. Fix what the tail reports (manifest or lockfile for `install`, Git state for `pull`), then deploy again.
|
|
31
|
+
- `PREVIEW_NOT_READY`: the revision landed but the preview never proved ready. `error.message` says what the check saw (a dev server that stopped, or a dependency that was still being optimized). Act on it before you read `fimo logs`, which can show a healthy dev server.
|
|
32
|
+
- No tail: run `fimo logs --json` before you retry, newest install and dev-server events first (`--cursor` or `--all-pages` for more). Do not replace the sandbox before you collect logs.
|
|
33
|
+
- `--no-wait` skips only the last readiness check; earlier failures still report.
|
|
112
34
|
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
```bash
|
|
116
|
-
curl https://your-site/index.md # .md suffix
|
|
117
|
-
curl -H 'Accept: text/markdown' https://your-site/ # content negotiation
|
|
118
|
-
curl https://your-site/?format=md # query param
|
|
119
|
-
```
|
|
35
|
+
### Blocked build scripts (`install_policy_blocked`)
|
|
120
36
|
|
|
121
|
-
This is a
|
|
122
|
-
|
|
123
|
-
## Recovering from Git drift
|
|
124
|
-
|
|
125
|
-
Most stale states are caught before deploy changes or commits files. Follow the emitted hint: clean a dirty checkout, or reconcile a diverged branch. A push can still lose a race if the remote advances after preflight:
|
|
126
|
-
|
|
127
|
-
```bash
|
|
128
|
-
git pull --rebase fimo <branch> # <branch> = the Branch you're deploying (e.g. main)
|
|
129
|
-
# fix any conflicts
|
|
130
|
-
fimo deploy
|
|
131
|
-
```
|
|
37
|
+
This is a project security policy, not a sandbox fault. Follow `error.details.repair`. Review each named package, then approve only those packages with the project's own setting:
|
|
132
38
|
|
|
133
|
-
|
|
39
|
+
- **pnpm:** add each package to `allowBuilds` in `pnpm-workspace.yaml`.
|
|
40
|
+
- **Yarn:** set `dependenciesMeta.<package>.built` in `package.json`.
|
|
41
|
+
- **Bun:** add the package to `trustedDependencies` in `package.json`, or run the exact `bun pm trust <packages>` command from the error.
|
|
42
|
+
- **npm:** has no per-package approval. Fix the failed script itself; do not change a trust policy.
|
|
134
43
|
|
|
135
|
-
|
|
136
|
-
- **Never** edit `.fimo/project.json`; it is generated by `fimo init`.
|
|
137
|
-
- Each Branch deploys to its own preview sandbox; `--publish` and `fimo publish` run from the configured Production source Branch only. See `references/branches.md`.
|
|
44
|
+
Run the same install locally, commit the policy and the lockfile, then deploy again. **Never use `dangerouslyAllowAllBuilds`, `enableScripts`, or another allow-all switch.**
|
|
138
45
|
|
|
139
|
-
##
|
|
46
|
+
## Hosting facts
|
|
140
47
|
|
|
141
|
-
-
|
|
142
|
-
-
|
|
48
|
+
- Fimo hosts the site. Preview runs `runtime.commands`, else the package script, else the framework default. Production builds from `.fimo/config.json#runtime.framework` with the same build and install overrides. An existing app keeps its router and hosting setup: do not replace the router, and do not derive rewrites from `.fimo/config.json#routes`. Framework setup (React Router `fimoPreset()`, plain Vite SPA catch-all): fimo-code `frameworks/hosting`; Astro: `frameworks/astro`. Redirects, headers, and URL shape: `--ref hosting`.
|
|
49
|
+
- **Markdown for AI agents:** Fimo hosting also serves a Markdown copy of each prerendered page (`/page.md`, `Accept: text/markdown`, or `?format=md`) and an `/llms.txt` index. Fimo makes these; never add a route that does it, and never add a route that fetches the site's own public URL. For a dynamic page, render Markdown from the same server data when the framework supports it; otherwise report the gap.
|
|
50
|
+
- **Warm-up:** the first deploy of a project provisions the sandbox, so it is slower than later deploys. When the user already asked for a hosted preview or a publish later in the session, you can start that deploy early in the background. The new-site first preview is already the warm-up.
|
|
51
|
+
- After the first deploy, change the site URL with `--ref domains`: a free `*.fimo.site` rename, a domain the user owns (Starter or higher), or a new domain bought through Fimo.
|
|
@@ -1,154 +1,61 @@
|
|
|
1
1
|
# Domains
|
|
2
2
|
|
|
3
|
-
`fimo domains`
|
|
3
|
+
`fimo domains` manages every site address. There are three kinds. Find out which one the user wants before you run a command:
|
|
4
4
|
|
|
5
|
-
|
|
|
6
|
-
|
|
|
7
|
-
|
|
|
8
|
-
|
|
|
9
|
-
|
|
|
5
|
+
| User says | Kind | Commands | Plan |
|
|
6
|
+
| ------------------------------------------ | ----------------------------------------- | ----------------------------------- | ------------------------------------------------------------- |
|
|
7
|
+
| "Keep the free address, but make it nicer" | default URL `<slug>.fimo.site` (one each) | `rename-default`, `suggest-default` | every plan, no DNS |
|
|
8
|
+
| "I own example.com" | custom domain, attached through DNS | `add`, `refresh`, `remove` | Starter or higher |
|
|
9
|
+
| "I want to buy a domain" | registered domain, bought through Fimo | `search`, `pricing`, `buy`, `owned` | purchase must be enabled; `buy` and `owned` need an org admin |
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
If the user is not sure, start with `fimo domains suggest-default`: it is free and takes one step. `fimo domains list --json` shows the default URL and every custom domain. Run `fimo domains <command> --help` for flags.
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
**A new default URL or custom domain shows "Project Not Found" until the site is published** (`fimo deploy --publish`, only when the user says to go live).
|
|
14
|
+
|
|
15
|
+
## Default URL
|
|
14
16
|
|
|
15
17
|
```bash
|
|
16
|
-
#
|
|
17
|
-
fimo domains
|
|
18
|
-
fimo domains
|
|
19
|
-
fimo domains suggest-default # propose & claim a default URL
|
|
20
|
-
fimo domains suggest-default --base "Acme Blog" # use a custom base instead of project display name
|
|
21
|
-
fimo domains suggest-default --pick 0 # non-interactive: claim the first suggestion
|
|
22
|
-
|
|
23
|
-
# Custom domain (Premium, user owns the hostname)
|
|
24
|
-
fimo domains add <hostname> # attach a custom domain
|
|
25
|
-
fimo domains add <hostname> --redirect-www # also configure an apex → www redirect
|
|
26
|
-
fimo domains add <hostname> --wait # block until SSL is active (5 min default)
|
|
27
|
-
fimo domains add <hostname> --wait 10m # poll for a custom duration (Ns / Nm)
|
|
28
|
-
fimo domains refresh <hostname> # re-check DNS / SSL (polls by default)
|
|
29
|
-
fimo domains refresh <hostname> --no-wait # one snapshot, no polling
|
|
30
|
-
fimo domains remove <hostname> # detach a custom domain
|
|
31
|
-
|
|
32
|
-
# Registered domain (Premium, buy a new domain through Fimo)
|
|
33
|
-
fimo domains search <keyword> # find available domains to buy
|
|
34
|
-
fimo domains search <keyword> --tld com,io # restrict TLDs
|
|
35
|
-
fimo domains search <keyword> --max-price 20 # purchase-price ceiling in dollars
|
|
36
|
-
fimo domains search <keyword> --limit 10 # truncate to first N results (default 20)
|
|
37
|
-
fimo domains pricing <domain> # one-shot price check
|
|
38
|
-
fimo domains buy <domain> # create checkout invoice (interactive confirm)
|
|
39
|
-
fimo domains buy <domain> --years 1 --yes # non-interactive (for agents)
|
|
40
|
-
fimo domains buy <domain> --open --wait # auto-open checkout in browser + poll until paid
|
|
41
|
-
fimo domains buy <domain> --wait 10m # poll for a custom duration (Ns / Nm)
|
|
42
|
-
fimo domains owned # list domains registered through Fimo
|
|
43
|
-
fimo domains owned --status owned,pending_payment
|
|
44
|
-
fimo domains owned --limit 10 # truncate to first N results
|
|
18
|
+
fimo domains rename-default <slug> --json # slug only: acme-coffee, not acme-coffee.fimo.site
|
|
19
|
+
fimo domains suggest-default --base "<brand>" --json # candidates; --json claims nothing
|
|
20
|
+
fimo domains suggest-default --base "<brand>" --pick <slug-or-index> --json # claim one
|
|
45
21
|
```
|
|
46
22
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
## Choosing the right resource
|
|
50
|
-
|
|
51
|
-
When a user says "I want to change my website's URL," ask which case fits:
|
|
52
|
-
|
|
53
|
-
- **"It's fine as-is, just nicer"** → `rename-default` or `suggest-default`. Free, instant, no DNS.
|
|
54
|
-
- **"I own example.com already"** → `add example.com`. Starter or higher. They configure CNAME at their registrar.
|
|
55
|
-
- **"I want to buy a domain"** → `search` → `pricing` → `buy`. The registered-domains feature flag and an eligible plan must be on (the flag is not enabled in every environment).
|
|
56
|
-
|
|
57
|
-
If they aren't sure, run `fimo domains suggest-default` first — it's free, takes one step, and a good fallback if they don't want to commit to a domain purchase.
|
|
58
|
-
|
|
59
|
-
## Offer a cleaner default URL before first publish
|
|
60
|
-
|
|
61
|
-
After the automatic first-preview deploy on a newly created project, offer a cleaner free `*.fimo.site` URL before the first public publish when there is no custom domain and the current default slug still looks generated or was never explicitly chosen. Choosing it now lets the first public launch use the clean URL. Skip the offer if the user already chose the default slug, attached a custom domain, or declined.
|
|
62
|
-
|
|
63
|
-
The default URL is free and needs no DNS. A custom domain needs Starter or higher, as above. A default slug can be reserved before publication, but it returns "Project Not Found" until the site is published. Renaming changes the address that will become public, so never silently claim a suggestion:
|
|
64
|
-
|
|
65
|
-
1. Run `fimo domains suggest-default --base "<brand>" --json` to get candidates.
|
|
66
|
-
2. Show the candidates and ask the user to choose one explicitly.
|
|
67
|
-
3. After confirmation, run `fimo domains rename-default <slug>` or `fimo domains suggest-default --pick <slug>`.
|
|
68
|
-
|
|
69
|
-
Choosing the slug does not publish the site. The first successful `fimo deploy --publish` makes the renamed URL resolve.
|
|
70
|
-
|
|
71
|
-
## Pricing & how money moves
|
|
72
|
-
|
|
73
|
-
The CLI never charges directly. Two distinct money paths:
|
|
74
|
-
|
|
75
|
-
1. **Starter or higher** — gates custom-domain operations. Starter or Pro is chosen in the Fimo web app (Hyperline-hosted checkout). When a Free user runs a gated command they get a 403 with the billing URL; surface it as-is to the user.
|
|
76
|
-
2. **Domain registration** — `fimo domains buy` creates a Hyperline invoice with `payment_method_strategy: 'external'` and returns a `checkoutUrl`. The user opens that URL in a browser to pay. **No money moves until they pay the invoice.** That's why `--yes` on `buy` is safe: it queues an invoice; the human still has to consent at checkout.
|
|
77
|
-
|
|
78
|
-
Domain prices come from name.com via the registrar reseller. They vary by TLD and can change. Pricing is in USD (cents in the API, formatted as dollars in CLI output).
|
|
23
|
+
A slug uses lowercase letters, numbers, and hyphens (at most 63). To change the address, use `rename-default`; never `add` a `*.fimo.site` hostname.
|
|
79
24
|
|
|
80
|
-
|
|
25
|
+
### Cleaner default URL before the first publish
|
|
81
26
|
|
|
82
|
-
|
|
27
|
+
After the first preview of a new site, offer a cleaner free URL when the current slug looks generated or the user never chose it, and the site has no custom domain. Skip it when the user already chose a slug, attached a domain, or said no.
|
|
83
28
|
|
|
84
|
-
1.
|
|
85
|
-
2.
|
|
86
|
-
3.
|
|
29
|
+
1. Run `fimo domains suggest-default --base "<brand>" --json`.
|
|
30
|
+
2. Show the candidates and ask the user to choose one. **Never claim a slug the user did not choose.**
|
|
31
|
+
3. Run `fimo domains rename-default <slug>` (or `--pick <slug>`).
|
|
87
32
|
|
|
88
|
-
|
|
33
|
+
Choosing the slug does not publish the site. The URL resolves after the first successful publish.
|
|
89
34
|
|
|
90
|
-
|
|
91
|
-
5. **Surface the `checkoutUrl` prominently.** The agent's message should make it obvious the user must click the link to actually pay. Example:
|
|
92
|
-
|
|
93
|
-
> "Invoice created. Open this to pay — no charge until you do:
|
|
94
|
-
> https://checkout.hyperline.co/abc123"
|
|
95
|
-
|
|
96
|
-
6. **Mention `--no-auto-renew`** in step 3 if appropriate. It's a recurring yearly charge otherwise.
|
|
97
|
-
7. Optionally **`--wait`** on the buy call so the agent can confirm registration completed (poll up to 5 min). For longer waits, ask the user to re-run `fimo domains owned` later.
|
|
98
|
-
|
|
99
|
-
## Custom domain (`add`) — the DNS dance
|
|
35
|
+
## Custom domain the user owns
|
|
100
36
|
|
|
101
37
|
```bash
|
|
102
|
-
fimo domains add
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
Add `--redirect-www` to also configure an apex → www redirect for the hostname.
|
|
106
|
-
|
|
107
|
-
Fimo prints DNS records the user copies to their registrar (Cloudflare, Namecheap, GoDaddy, etc.):
|
|
108
|
-
|
|
38
|
+
fimo domains add <hostname> [--redirect-www] [--wait [10m]] --json # --redirect-www: the apex redirects to www; bare --wait = 5 min (Ns or Nm)
|
|
39
|
+
fimo domains refresh <hostname> # check DNS and SSL again; it polls by default
|
|
40
|
+
fimo domains remove <hostname> --yes
|
|
109
41
|
```
|
|
110
|
-
DNS records to add at your registrar:
|
|
111
|
-
|
|
112
|
-
TYPE NAME VALUE
|
|
113
|
-
CNAME blog customers.fimo.site
|
|
114
|
-
TXT _fimo verify=abc123…
|
|
115
|
-
```
|
|
116
|
-
|
|
117
|
-
Run `fimo domains refresh blog.example.com` after configuring DNS to re-check. `refresh` polls by default; `--no-wait` for a snapshot.
|
|
118
|
-
|
|
119
|
-
Propagation: typically 15–30 minutes, up to 48 hours rarely.
|
|
120
|
-
|
|
121
|
-
## Common errors
|
|
122
|
-
|
|
123
|
-
- **"Project Not Found" on a new URL or custom domain.** The route exists but the site was never published — run `fimo deploy --publish`.
|
|
124
|
-
- **"Custom domains require Starter or higher."** — choose a plan at `/app/billing`, then retry. Free users can still run `list`, `rename-default`, `suggest-default`, `search`, and `pricing`.
|
|
125
|
-
- **"Domain purchase is not enabled on this account."** — the registered-domains feature flag is off on this API instance. Contact support.
|
|
126
|
-
- **"This URL is not available."** — slug or hostname collides with another project or is reserved.
|
|
127
|
-
- **"That's a Fimo-owned domain."** — user tried `add <something>.fimo.site`. Use `rename-default` instead.
|
|
128
|
-
- **"Invalid URL."** — slug violates RFC 1123 (lowercase letters, numbers, hyphens; max 63 chars).
|
|
129
|
-
- **"`<domain>` is not available for registration."** — the requested registered domain is taken or otherwise unbuyable. Suggest `search` to find alternatives.
|
|
130
|
-
- **"`<domain>` is a premium domain and isn't supported through the CLI."** — name.com flags some domains as premium with elevated prices; the CLI deliberately rejects these to avoid surprise charges. Direct the user to a different name.
|
|
131
|
-
- **"You don't have permission to buy domains for this organization. Org admins only."** — org admin role required for `buy` and `owned`.
|
|
132
|
-
- **"Couldn't sync the URL."** — transient Cloudflare KV write failure. Retry.
|
|
133
|
-
|
|
134
|
-
## When to use `--wait`
|
|
135
42
|
|
|
136
|
-
|
|
43
|
+
- `add` returns the DNS records (usually a CNAME and a TXT) that the user sets at their registrar; with `--json` they are in the domain record. Give them to the user exactly.
|
|
44
|
+
- After the user sets DNS, run `refresh` once; it polls until SSL is active or the wait ends (`--no-wait` prints one status). Read the returned status: the end of a wait does not prove the domain works. Do not run `refresh` in a loop. DNS can take from minutes to 48 hours.
|
|
45
|
+
- In an interactive setup, omit `--wait` on `add` so the user gets the records at once. In CI, `--wait` polls until the domain is verified or the wait ends.
|
|
46
|
+
- A Free plan gets a `PAYWALL` 403 with the billing URL: give that URL to the user.
|
|
47
|
+
- `remove` and `buy` ask for confirmation: pass `--yes` in a run without prompts, after the user agreed.
|
|
137
48
|
|
|
138
|
-
|
|
139
|
-
- **Interactive user setup**: omit `--wait` on `add` so they get the DNS table immediately and can paste it into their registrar.
|
|
140
|
-
- **`refresh`**: defaults to wait because if a user is explicitly refreshing they want the new state. Pass `--no-wait` to opt out.
|
|
141
|
-
- **`buy`**: opt-in via `--wait`. The poll covers "payment landed" + "name.com registration completed."
|
|
49
|
+
## Buy a domain (paid)
|
|
142
50
|
|
|
143
|
-
|
|
51
|
+
`buy` creates an invoice and returns a `checkoutUrl`. No money moves until the user pays in the browser. Registration is usually not refundable, and auto-renew is on by default (a yearly charge).
|
|
144
52
|
|
|
145
|
-
|
|
53
|
+
1. Run `fimo domains search <keyword> [--tld com,io] --json`, or `fimo domains pricing <domain> --json`. **Never run `buy` before you check the price.**
|
|
54
|
+
2. Show the candidates with prices, for example `acme.com — $14.00 first year, $14.00/yr renewal`.
|
|
55
|
+
3. Get the user's explicit approval for the domain, the years, and auto-renew (`--no-auto-renew` to turn it off).
|
|
56
|
+
4. Run `fimo domains buy <domain> [--years <n>] [--no-auto-renew] --yes --json` (`--wait` polls until payment and registration finish, fail, or the wait ends).
|
|
57
|
+
5. **Show the `checkoutUrl` clearly**, and say that the user must open it to pay. Later status: `fimo domains owned`.
|
|
146
58
|
|
|
147
|
-
|
|
59
|
+
The CLI refuses names that the registrar prices as premium: suggest another name.
|
|
148
60
|
|
|
149
|
-
|
|
150
|
-
- **Forgetting that registered-domain purchases are typically non-refundable.** ICANN rules; once registered, you generally own it for the term.
|
|
151
|
-
- **Trying to `add` a `*.fimo.site` hostname** — that's the default URL. Use `rename-default` to change the slug. The CLI catches this.
|
|
152
|
-
- **Running `refresh` in a manual loop** — it polls by default; let it run. Manual loops waste API calls and may trigger 429s.
|
|
153
|
-
- **Forgetting `--yes` in scripts** — `remove` and `buy` confirm by default; pass `--yes` or they hang in a non-TTY.
|
|
154
|
-
- **Surfacing the `buy` checkout URL too quietly.** The user must visit the URL to pay; if the agent buries it in a long message they may miss the next step.
|
|
61
|
+
Studio equivalent: Settings → Domains (custom domain), Organization → Domains (buy, owned); see the `fimo-studio` skill's `custom-domains`.
|
|
@@ -43,7 +43,7 @@ The list response includes `nextCursor` when another page exists. `--offset` rem
|
|
|
43
43
|
- `delete` removes one submission permanently and prints the deleted record. There is no undo, no bulk delete, and no confirmation prompt — confirm with the user before running it. An unknown or already-deleted id fails with `Submission not found`.
|
|
44
44
|
- There's no CLI command to create a submission. Submissions are created by the form intake endpoint when a user submits the published site's form.
|
|
45
45
|
|
|
46
|
-
Use this when the user asks "who filled out the contact form?", "how many signups did we get this week?", or "show me the latest submission".
|
|
46
|
+
Use this when the user asks "who filled out the contact form?", "how many signups did we get this week?", or "show me the latest submission". To show someone where submissions are in Studio, or for older submissions and bulk export, read the `fimo-studio` skill's `cms` reference before you name a screen — there's no batch export endpoint yet.
|
|
47
47
|
|
|
48
48
|
## "Add a contact form" recipe
|
|
49
49
|
|