The seaforms command
seaforms saves your site’s published forms in your project as files, each with a TypeScript type for its answers. It needs Node 22 or later, and nothing to install:
npx seaforms loginnpx seaforms pullpnpm dlx seaforms loginpnpm dlx seaforms pullyarn dlx seaforms loginyarn dlx seaforms pullbunx seaforms loginbunx seaforms pullCommands
Section titled “Commands”| Command | What it does |
|---|---|
login | Shows a page and a code, opens the page in your browser, and waits while you approve it in the app. It signs in to the workspace you approve it for. |
link | Chooses which of your sites this project is: your only site built with code is picked for you; with several, it asks. Saves seaforms.json at the project's root. Commit it. |
pull [forms…] | Saves the site's published forms (or only those named) as <name>.seaforms.json, each with <name>.seaforms.d.ts beside it. Links first if the project isn't linked. |
types [files or folders…] | Writes the types for form files already in the project, such as one downloaded from the app. No sign-in and no network. |
whoami | Who you're signed in as, in which workspace, and this project's site. |
logout | Ends the sign-in on Seaforms, then forgets it on this computer. |
Options
Section titled “Options”| Option | With | What it does |
|---|---|---|
--site <id> | link, pull | The site to use (site_…), instead of asking. |
--dir <folder> | link, pull, types | Where form files go: src/forms by default, or forms when there's no src. Saved in seaforms.json, and always inside the project. |
--no-types | pull | Pull without writing types. |
--no-browser | login | Show the page to open without opening it, for a machine with no browser. |
--api <url> | every command but types | Another Seaforms server, for testing. Also SEAFORMS_API. |
npx seaforms help lists them, and npx seaforms --version says which version you have.
Signing in
Section titled “Signing in”$ npx seaforms loginTo sign in, open this page: https://app.seaforms.io/device?user_code=KQWXPLMNand check it shows the code KQWX-PLMN.(It's opening in your browser.)Waiting for you to approve it… Press Ctrl+C to stop.Signed in as maya@northwind.co, in Northwind.Next: npx seaforms pull saves your site's forms in this project.The page shows what’s asking and where from. Approve it in the workspace you want the CLI to work in; you’re emailed that it signed in.
- It can only read. The CLI asks for nothing but your workspace’s sites and its forms, so its sign-in can’t change anything.
- Kept in your config folder, never in the project:
~/.config/seaforms/auth.json(%APPDATA%\Seaformson Windows, orSEAFORMS_CONFIG_DIR), readable only by you. It’s never printed. - It lasts 30 days after you last use it, 90 at most. Then
loginagain. logoutends it on Seaforms, not only here. You can also see and end it in the app, under Settings, then Profile.
Pulling
Section titled “Pulling”$ npx seaforms pullNorthwind's forms, into src/forms:✔ contact revision 3, saved· quote revision 7, already up to date– survey not published yet: publish it in the app firstRebuild and deploy your site to put the change on its pages.- Only published forms. A form’s draft never reaches your code.
- Byte for byte the app’s download. A pulled file is exactly what Download the file for your code in the app saves, so the two are interchangeable.
- Written only when it changes, so pulling again leaves git alone.
- Never deleted. A file whose form was renamed or deleted in the app is pointed out, for you to remove once nothing imports it.
- One form at a time:
npx seaforms pull contact quote.
Which project
Section titled “Which project”The project is the nearest folder above you with a seaforms.json, package.json or .git. In a monorepo, run it in the package whose site it is: its seaforms.json goes there.
Set SEAFORMS_API_KEY to an API key that can read forms, commit seaforms.json, and npx seaforms pull needs nothing else. See In CI.
ChatGPT is a trademark of OpenAI, and Claude and Claude Code are trademarks of Anthropic. Other product names and logos belong to their owners. None of them makes or endorses Seaforms. Trademarks