POC · feat/fimo-cli-poc

Fimo CLI

Shipped .worktrees/fimo-cli-poc

What this POC proves

Developers can create, manage, and deploy a Fimo project entirely from the terminal using Claude Code — with no mandatory web interface. Marketing teams retain full autonomy over content through the dashboard; their edits land as git commits that never disrupt local dev (no conflicts, no rebases required from content changes).

Commands

Auth & project

shell

fimo login                    # browser-based auth → ~/.config/fimo-cli/credentials.json
fimo signup                   # email/password signup
fimo whoami                   # sanity check
fimo create <dir>             # scaffold + link to Fimo
fimo rename "Display Name"    # set project display name

Deploy

shell

fimo deploy                   # push main → sandbox sync (preview URL)
fimo deploy --publish        # same + trigger live publish

Content

shell

fimo schema push [TypeName]  # push JSON schema (create or update)
fimo schema list | get <T> | delete <T>

fimo entries create <T> --body '<json>'
fimo entries list <T> | get <T> <id> | update <T> <id> --body '<json>' | delete <T> <id>

Assets

shell

fimo assets upload <file>
fimo assets generate --prompt "..." [--aspect-ratio 16:9]
fimo assets list | create-folder <n> | move <id> --parent-id <fid> | delete <id>

Forms & translations

shell

fimo forms push [name]
fimo forms list | get <id> | delete <id>

fimo translations sync         # extract t() → translations/en.json → push diff
fimo translations list [--locale en]

All commands output JSON to stdout. All commands accept --json for script-friendly output and FIMO_API_TOKEN env var to bypass interactive login (CI use).

Template

apps/cli/assets/template/default/ — the new CLI project template. Source-tracked; no .fimo/ folder. Uses fimo/ui and fimo/vite instead of the old internal copies. Separate from apps/api/templates/default/ (sandbox-managed) because the two have different lifecycles — a divergence tracked as N3 in the RFC.

Claude starter

Copied into <project>/.claude/ by fimo create from apps/cli/assets/claude-starter/.

skills/fimo/SKILL.md + references/{content,assets,forms,translations,analytics}.md — reference docs for the in-project AI agent
rules/fimo.md — project rules: never auto-deploy, never edit .fimo.settings.json, read before writing
settings.json — pre-approved fimo:*, pnpm:*, git:* permissions

Backend additions

GET /api/management/projects/:id/git-remote

Returns signed git URL for push/pull. Not in ProjectDTO (URL is time-limited).

POST /api/management/projects/:id/sandbox/pull

Runs git fetch + reset --hard origin/main inside the sandbox.

No changes to auth, /publish, or existing project endpoints.

Architecture decisions & shortcuts

Deploy only pushes main

Simplest path; branch support is out of POC scope.

CLI template is separate from apps/api/templates/default/

API template is sandbox-managed; CLI template is user-managed. Different lifecycles.

fimo deploy wraps git push + sandbox pull (not a raw remote)

Hides signed-URL rotation and sandbox sync complexity from the user.

fimo deploy is user-initiated only — no slash command

Prevents AI from auto-deploying after code changes.

Auth stored as bearer token in ~/.config/fimo-cli/credentials.json

Mirrors apps/api/cmd/utils.ts pattern; no new auth mechanism.

No npx fimo create yet

Requires publishing to npm; deferred.

Known limitations

main only

fimo deploy always pushes to main. No branch support.

One sandbox per project

No preview environments per branch.

Dashboard silent about CLI state

The web dashboard doesn't indicate that code now lives in git — no sync status, no pending-push state, no environment badge. Editors can't tell what the CLI side is doing. RFC N2 addresses this.

Translations storage split

Translations live in both a git file and a tenant DB. They can diverge. The RFC proposes making the DB the single source of truth with a fimo/vite plugin for autoload.

Sandbox pull races editor

If the Fimo dashboard is actively editing files when fimo deploy runs, the pull may overwrite uncommitted sandbox changes. Documented as unsupported.

Git push URL expires

TTL is generous for interactive sessions; CLI re-fetches on failure, but long-running CI jobs may hit the limit.

Pending

Designed but not yet implemented. Full designs in the RFC.

fimo studio

A lightweight admin UI for local content management — content, media, translations, form submissions — without requiring the Fimo web app. Auth via one-time token, no second login.

Full design in RFC →

Translations storage rework

Translations currently diverge between git and the tenant DB. The RFC proposes making the DB the single source of truth, with a fimo/vite plugin fetching and watching translations at dev/build time.

Full design in RFC →

Key files

apps/cli/
├── assets/
│   ├── template/default/         # New CLI project template (fimo/ui + fimo/vite)
│   ├── content-templates/        # hooks-template-v3.eta, form-template.eta
│   └── claude-starter/           # Copied to <project>/.claude/ on fimo create
│       ├── skills/fimo/          # SKILL.md + references/
│       ├── rules/fimo.md
│       └── settings.json
└── src/cli/
    ├── index.ts                  # Commander entry
    ├── commands/
    │   ├── login.ts, signup.ts, whoami.ts, switch.ts
    │   ├── create.ts             # scaffold + git init + link
    │   ├── deploy.ts             # push + sandbox pull + optional publish
    │   ├── schema.ts, entries.ts, assets.ts, forms.ts, translations.ts
    │   └── rename.ts
    ├── api.ts                    # FimoApiClient
    ├── auth.ts                   # credential load/save
    ├── config.ts                 # FIMO_API_URL, FIMO_WEB_URL
    └── utils/
        └── project.ts            # resolveProjectCwd, loadProjectSettings

apps/api/src/http/routes/management/projects/sandbox.ts
    # GET /:id/git-remote
    # POST /:id/sandbox/pull

How to run locally

Build and link the binary

pnpm -F fimo install-cli    # build + symlink ~/.local/bin/fimo

Create a project

fimo create my-project
cd my-project

Start dev server

pnpm dev

Deploy — user runs this, not the AI

fimo deploy             # preview
fimo deploy --publish  # go live