Skip to content

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:

Terminal window
npx seaforms login
npx seaforms pull
CommandWhat it does
loginShows 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.
linkChooses 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.
whoamiWho you're signed in as, in which workspace, and this project's site.
logoutEnds the sign-in on Seaforms, then forgets it on this computer.
OptionWithWhat it does
--site <id>link, pullThe site to use (site_…), instead of asking.
--dir <folder>link, pull, typesWhere form files go: src/forms by default, or forms when there's no src. Saved in seaforms.json, and always inside the project.
--no-typespullPull without writing types.
--no-browserloginShow the page to open without opening it, for a machine with no browser.
--api <url>every command but typesAnother Seaforms server, for testing. Also SEAFORMS_API.

npx seaforms help lists them, and npx seaforms --version says which version you have.

Terminal window
$ npx seaforms login
To sign in, open this page:
https://app.seaforms.io/device?user_code=KQWXPLMN
and 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%\Seaforms on Windows, or SEAFORMS_CONFIG_DIR), readable only by you. It’s never printed.
  • It lasts 30 days after you last use it, 90 at most. Then login again.
  • logout ends it on Seaforms, not only here. You can also see and end it in the app, under Settings, then Profile.
Terminal window
$ npx seaforms pull
Northwind'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 first
Rebuild 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.

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.

Was this helpful?

Your answer goes straight to the person who wrote it.

Thanks. We read every note and update the article.

Thanks, that helps us keep these useful.

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