Planned API and CLI

Planned API and CLI

This page transcribes the team's specification for the planned SaaS API and the full CLI — none of this exists in the code yet. See CLI for the single transf-orm convert command implemented so far, and Vision for how this fits the overall roadmap.

1. Roles & permissions

Three hierarchical access levels, scoped to a team.

Role	Cardinality	Scope
Owner	One per team	Inherits all Admin rights, plus deleting the team and transferring ownership. Cannot be removed or demoted without a prior ownership transfer.
Admin	Several per team	Manages billing, invitations, and removing regular members. Cannot act on another admin or on the owner.
Member	—	Access to projects, transformations, history, and revert, within the team's quota.

2. API route reference

2.1 Authentication & account

Method	Route	Description	Access
POST	/auth/register	Create an account.	Public
POST	/auth/login	Log in.	Public
POST	/auth/logout	Log out.	Authenticated
POST	/auth/refresh	Refresh the token.	Authenticated
GET	/me	Current user's profile.	Authenticated
PATCH	/me	Update the profile.	Authenticated

2.2 Teams

Method	Route	Description	Access
POST	/teams	Create a team (the creator becomes owner).	Authenticated
GET	/teams/{id}	Team details.	Member
PATCH	/teams/{id}	Update general team information.	Admin+
DELETE	/teams/{id}	Delete the team.	Owner
POST	/teams/{id}/transfer-ownership	Transfer ownership. Body: { newOwnerId }.	Owner
GET	/teams/{id}/members	List members.	Member
POST	/teams/{id}/members/invite	Invite a member. Body: { email, role }.	Admin+
DELETE	/teams/{id}/members/{userId}	Remove a member (cannot target the owner).	Admin+
PATCH	/teams/{id}/members/{userId}	Change a member's role. Target member: Admin+. Target admin: Owner only.	Admin+ / Owner

2.3 Billing

Method	Route	Description	Access
GET	/teams/{id}/billing/plan	The team's current plan.	Admin+
POST	/teams/{id}/billing/checkout	Subscribe or change plan. Body: { planId }.	Admin+
GET	/teams/{id}/billing/usage	Current usage: project count, member count, monthly transformations.	Admin+

Billing model: fixed plans, scoped to the team. See Vision for the plan tiers.

2.4 ORM registry

Method	Route	Description	Access
GET	/orms	List of ORMs supported by the platform.	Public / Authenticated

2.5 Projects

Method	Route	Description	Access
GET	/teams/{id}/projects	Projects the user collaborates on.	Member
POST	/teams/{id}/projects	Create a project (creator becomes a collaborator automatically). Refused with 402/403 if the team quota is reached.	Member
GET	/projects/{id}	Project details.	Collaborator
PATCH	/projects/{id}	Update a project.	Collaborator
DELETE	/projects/{id}	Delete a project.	Admin+
GET	/projects/{id}/collaborators	List a project's collaborators.	Collaborator
POST	/projects/{id}/collaborators	Add a collaborator. Body: { userId } (must already be a team member).	Collaborator
DELETE	/projects/{id}/collaborators/{userId}	Remove a collaborator.	Collaborator

Visibility is collaborator-scoped (GitHub-style): a project is only visible and editable by members explicitly added to it, not the whole team.

2.6 Schema files

Method	Route	Description	Access
POST	/projects/{id}/files	Manual multipart upload, or automatic import from the linked repo via { source: "repo" }. Triggers ORM detection.	Collaborator
GET	/projects/{id}/files	List tracked files.	Collaborator
GET	/projects/{id}/files/{fileId}	A file's content and metadata.	Collaborator
DELETE	/projects/{id}/files/{fileId}	Delete a file.	Collaborator
GET	/projects/{id}/detected-orm	Result of automatic ORM detection.	Collaborator

Schema files are stored at the project level.

2.7 Transformation (asynchronous)

Method	Route	Description	Access
POST	/projects/{id}/transform	Start a transformation. Body: { from?, to, fileIds[], description? }. Responds 202 with a job_id.	Collaborator
GET	/jobs/{job_id}	Job status (pending / running / partial / done / failed) and result or suggestions.	Collaborator
GET	/jobs/{job_id}/stream	Real-time progress (SSE / WebSocket).	Collaborator
DELETE	/jobs/{job_id}	Cancel a running job.	Collaborator

2.8 Git integrations (GitHub, GitLab, etc.)

Method	Route	Description	Access
GET	/teams/{id}/integrations	Git integrations connected to the team.	Admin+
POST	/teams/{id}/integrations/{provider}/connect	Start the OAuth flow (provider = github / gitlab / ...).	Admin+
GET	/teams/{id}/integrations/{provider}/callback	OAuth callback (provider redirect).	Public, validated by state/token
DELETE	/teams/{id}/integrations/{provider}	Disconnect the integration.	Admin+
GET	/teams/{id}/integrations/{provider}/repos	Repos accessible via the connected token.	Admin+
POST	/projects/{id}/repo/link	Link a repo to a project. Body: { provider, repoId, branch, autoImport? }. If autoImport: true, automatically imports detected schema files.	Collaborator
DELETE	/projects/{id}/repo/link	Unlink the repo from the project.	Collaborator
POST	/projects/{id}/repo/push	Open a Pull Request with the transformed schema. Body: { fileIds[], commitMessage, branch?, prTitle?, prDescription? }. Always via PR, never a direct push.	Collaborator
GET	/projects/{id}/repo/status	Linked repo status (branch, last opened or merged PR).	Collaborator

The OAuth connection is team-scoped: the token belongs to the team, not an individual member, so access isn't lost when someone leaves. The repo is then linked to a specific project.

2.9 History & revert

Method	Route	Description	Access
GET	/projects/{id}/history	List of modified files.	Collaborator
GET	/projects/{id}/history/{fileId}/versions	Available versions for a file.	Collaborator
GET	/projects/{id}/history/{fileId}/diff?version=	git/VS-Code-style diff between two versions.	Collaborator
POST	/projects/{id}/revert	Revert. Body: { files: [{ fileId, version }] }.	Collaborator

History and revert are project-scoped.

3. CLI specification

Two execution modes: an interactive CLI mode (the default) and a server mode. A set of global flags applies regardless of mode.

3.1 Global flags

Flag	Description
-cli	Run in interactive CLI mode. Default if no mode is specified.
-serveur	Run in server mode (API) — see §3.4.
-debug <level>	Enable debug logs, with several verbosity levels.
-verbose	Increase standard output verbosity.
-perf	Enable performance metric tracking and display.
-tts	Enable text-to-speech for CLI feedback.
-daltonien	Enable a colorblind-friendly display mode (alternate contrast palette).
-h / --help	Show help and the list of available commands.
-version	Show the binary's version.

3.2 CLI mode (default)

The CLI always runs against the current directory. On startup it prints the name of the ORM automatically detected there. If no ORM is detected, the user must specify one explicitly via --from when calling transform.

3.3 CLI commands

transform

transform [--from <orm>] --to <orm> [--description <text>]

• --from is optional if the source ORM was auto-detected, required otherwise.
• --to is required and names the target ORM.
• --description is optional.
• Opens an interactive file picker (lazygit-style) to choose which detected schema files to translate.
• When no exact translation exists for a schema element, the CLI proposes alternatives if any exist, or explains why the translation isn't possible.

revert

revert

• Opens a picker to choose which files to revert, then a target version for each.
• A "select all" option is available, followed by a per-file version choice.

history

history

• Shows the list of modified files.
• Lets you pick one and view its diffs in a git-diff/VS-Code-style rendering.

3.4 Server mode

Enabled via the -serveur flag, exposing the API. Accepts these network configuration flags:

Flag	Description
--ip <address>	IP address the server listens on.
--port <port>	Listening port.
--host <host>	Hostname associated with the server.