npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@thesmallfield/cli

v0.0.7

Published

Deploy apps to Small Field from the command line

Readme

sf — the Small Field command line

Install

Needs Node 22 or newer.

npm i -g @thesmallfield/cli
sf --version      # 0.0.7

From source (contributors)

The shared packages (@thesmallfield/contracts, detect) come from GitHub Packages. Once per machine, let npm read them with your own GitHub login:

gh auth refresh -s read:packages
echo "//npm.pkg.github.com/:_authToken=$(gh auth token)" >> ~/.npmrc

Then:

git clone [email protected]:thesmallfield/cli.git
cd cli && pnpm install && pnpm build && pnpm add --global .
sf --version      # 0.0.7

pnpm add --global . puts sf on your PATH. If pnpm says its global bin folder is not in your PATH, run pnpm setup once and open a new terminal. Older pnpm versions can use pnpm link --global instead.

pnpm build bundles everything into one file, dist/main.js, so the published package has no dependencies. A GitHub release tagged v<version> publishes it to npm.

Sign in

$ sf login https://appsadmin.example.com/api
Open https://auth.apps.example.com/device?code=7HKM-2QWP and confirm the code 7HKM-2QWP
Waiting…
Signed in as [email protected] (admin)

sf tries to open the page in your browser; if it cannot (over SSH, say), open the link yourself. Check the code on the page matches, then approve. Only developers and admins can approve. The token is saved in ~/.config/smallfield/config.json (only you can read it). After the first time, sf login needs no address.

With no address the first time, sf login asks for it. The console host alone is fine; /api is added:

$ sf login
Small Field address (for example https://appsadmin.example.com/api): https://appsadmin.example.com
Open https://auth.apps.example.com/device?code=7HKM-2QWP and confirm the code 7HKM-2QWP
Waiting…
Signed in as [email protected] (admin)
$ sf whoami
[email protected] (admin) at https://appsadmin.example.com/api
$ sf logout
Signed out.

sf login --force signs in again even when the saved sign-in still works. If the API answers that the token is no longer valid, every command says Your sign-in expired. Run sf login.

For CI, set both SMALLFIELD_API_URL and SMALLFIELD_API_KEY (a personal sf_… token); together they win over the saved file. Never commit the token.

Questions and scripts

In a terminal, sf asks for what it needs: the address on the first sf login, whether to run sf init when sf deploy finds no smallfield.json, and the answers for sf init. sf logs, sf run and sf secrets remove let you pick from a list, and sf secrets set and sf env add ask for a missing name. Every question shows an example or a default; Enter takes the default; Ctrl-C stops with nothing changed (exit code 130). Questions go to stderr, so stdout keeps only results.

In a script or in CI it never asks: when CI is set, when stdin or stdout is not a terminal, or with --yes. Then it takes the defaults, answers yes, and otherwise prints the message and exits 1, so pass the name or flag:

$ sf login < /dev/null
Say which API, for example: sf login https://appsadmin.example.com/api
$ echo $?
1
$ sf --yes deploy < /dev/null
No smallfield.json here. Run sf init.

In a terminal, sf --yes deploy in a folder without smallfield.json runs sf init with what it found, asks nothing, then deploys. sf --yes init writes the same file as a script would.

sf init in a terminal, in a repo with a Vite app in apps/web and a Bun API with a db:migrate script in apps/api:

$ sf init
Is this a new project or one that already exists on Small Field?
  1) New
  2) Existing
Number [1]:
Found 2 components:
  api  web     apps/api  /api  port 8080
  web  static  apps/web  /
  Tip: api's code mentions /api, so the prefix will be kept ("stripPrefix": false).
Project name [rooms]: Rooms App
Use only lowercase letters, numbers and hyphens, up to 40 characters.
Project name [rooms]: rooms
api starts with Bun ("bun src/server.ts"). Set "runtime": "bun"? [Y/n]
api will live at /api. When someone opens /api/projects, what should your code receive?
  1) /projects       (remove /api; your routes start with /projects)
  2) /api/projects   (keep /api; your routes start with /api/...)
Number [2]:
api has a db:migrate script. Add a Postgres database and run "npm run db:migrate" before each deploy? [Y/n]
Write smallfield.json? [Y/n]
Wrote smallfield.json
Which environment should sf deploy use?
  1) development (default)
  2) staging
Number [1]: 2
sf deploy will use staging (saved in smallfield.local.json).

Deploy an app

sf init      # once, in a repo without smallfield.json
sf deploy
$ cd helloworld && sf deploy
Packing helloworld… 412 KB (skipped node_modules, dist, .env by .gitignore rules)
Uploading…
Deploying release 3f9c0a1b…
  building
  deploying
  live
https://helloworld-dev.apps.example.com/
$ echo $?
0

If the deploy fails, the last status line is failed, followed by the reason, and the exit code is 1. Running sf deploy again with no changes prints the same address.

In a folder without smallfield.json, sf deploy offers to run sf init first, then deploys ("n" stops with Nothing deployed. Run sf init when ready.). In a script it says No smallfield.json here. Run sf init. and exits 1.

$ cd rooms && sf deploy
No smallfield.json here. Run sf init now? [Y/n]
Found 1 component:
  rooms  static  .  /
Wrote smallfield.json
Packing rooms… 48 KB
Uploading…
Deploying release 3f9c0a1b…
  building
  deploying
  live
https://rooms-dev.apps.example.com/

Commands

Cheat sheet:

sf login [apiUrl]          sign in (once)              sf whoami / sf logout
sf init                    write smallfield.json       sf deploy [--env <name>]
sf status                  latest release              sf logs [component] [--lines n]
sf secrets set|list|remove  hidden values             sf env list / sf env add [name]
sf shared list             firm keys IT manages        sf shared request [name] --reason "…" [--as VARIABLE]
sf shared rename <key> <VARIABLE>                      sf shared usage <key> --by-value   (admin)
sf shared values <key>     admin: list values          sf shared values add|edit|disable|enable|remove <key> [id]
sf run [job]               start a job now             sf runs [--job <name>] / sf runs logs <runId>
sf maintenance on [--message "…"] / off / status   show visitors a maintenance page
sf releases [--limit n]    latest releases             sf rollback [id] / sf promote --to <env> [id]
sf db export <schema.table> [--filter col:op:value] [--sort col] [--desc] / --sql "select …"
sf db backup / backups / download <id> [--out file] / restore <backupId> [--confirm <project>/<env>]
sf db schedule --daily on|off [--keep n]   CSV exports, backups, restore (add --no-wait to not wait)
sf db rotate-password [name] [--project p] --env development   platform admin: new database password (app gets it on next deploy)
sf template publish <version> [--security] [--notes "…"]
sf template versions       VERSION, SECURITY, STATUS, FORKS, PUBLISHED, NOTES
sf --yes …                 never ask; take every default

sf releases, sf rollback, sf promote reuse the images of a release that went live. sf releases --env dev lists the latest releases with a short 8-character id. sf rollback 3f2a9c1e --env dev redeploys that older release; with no id it uses the live release before the current one. A rollback rebuilds nothing. sf promote --to production deploys what is live in --env (or a release you name) to another environment. It rebuilds only the components whose build settings differ in the target. Both show what changes, then ask (y/N); --yes skips the question. Secrets, database data, sign-in methods and domains stay as they are in the target. If production lacks a secret the release needs, sf promote asks for it (hidden); with --yes it stops and tells you to run sf secrets set NAME --env production.

sf init looks at the repo, lists the components it found and writes smallfield.json. In a terminal it first asks Is this a new project or one that already exists on Small Field?.

New never overwrites an existing smallfield.json. It asks (Enter takes the default):

| Question | When | Default | | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | --------------- | | Project name [<folder>]: | always | the folder name | | <c> starts with Bun (…). Set "runtime": "bun"? | a web component whose start script uses bun, or a bun.lock | yes | | How do I start <c>? (with an example and the guess as default) | a web component with runtime python or rust (replaces the Bun and db:migrate questions) | the guess | | <c> will live at <path>. When someone opens <path>/projects, …? | a web component whose path is not / | the guess | | <c> has a db:migrate script. Add a Postgres database and run "npm run db:migrate" …? | a web component with a db:migrate script | yes | | Does <project> need a Postgres database? | a web component and no db:migrate script | no | | Write smallfield.json? | always, last ("n" writes nothing and exits 1) | yes |

The stripPrefix guess: if the component's code has a string like '/api' or "/api/projects", the default is 2 (keep, "stripPrefix": false), otherwise 1 (remove, nothing written).

Existing needs sf login. Pick one of the projects you can deploy; sf init starts from what Small Field has for it (the last deploy plus what was set in the console). It asks only about components found here but not on Small Field, and keeps the ones it cannot find here:

$ sf init
Is this a new project or one that already exists on Small Field?
  1) New
  2) Existing
Number [1]: 2
Which project?
  1) helloworld
  2) rooms
Number [1]:
worker1 is on Small Field but not found here; kept.
Found api2 (web, api2) here but not on Small Field. Add it? [Y/n]
api2 will live at /api2. When someone opens /api2/projects, what should your code receive?
  1) /projects        (remove /api2; your routes start with /projects)
  2) /api2/projects   (keep /api2; your routes start with /api2/...)
Number [1]:
Write smallfield.json? [Y/n]
Wrote smallfield.json

With a smallfield.json already here, it offers to sync it. Small Field wins for every key it has; keys only here stay:

smallfield.json exists. Sync it from Small Field (project helloworld)? [Y/n]
  showInPortal added (Small Field)
  components.api1.port 3000 -> 4000 (Small Field)
  components.worker1 added (Small Field)
  components.api2 kept (only here)
Write smallfield.json? [Y/n]
Wrote smallfield.json

A project with nothing deployed yet is set up as New, keeping its name.

Last, sf init asks Which environment should sf deploy use?: the project's environments for Existing, your tenant's for New, with the tenant default first picked. A choice other than the default goes in smallfield.local.json ({ "environment": "staging" }), which sf deploy never uploads and sf init adds to .gitignore when there is one. Not signed in, New skips the question.

With a .env.example (or .env.sample, .env.template), sf init adds each name to smallfield.json as "secrets": { "NAME": "env" }: names only, never values. Lines that are not secret names are listed and skipped; names already declared as template or fork keep their scope. Signed in, after the environment question it saves the real values from your .env (not empty, not the example's placeholder) after one question, then asks for each other value with a hidden prompt (Enter skips):

.env.example lists 9 secrets. Added their names to smallfield.json (never values).
Which environment should sf deploy use? ...
.env has real values for 6 of them. Save those 6 to staging? [Y/n]
Saved VITE_SUPABASE_URL, VITE_SUPABASE_KEY, VITE_API_URL, VITE_MAPBOX_TOKEN, VITE_SENTRY_DSN, VITE_POSTHOG_KEY.
VITE_APP_REDIRECT_URI (Enter to skip):
Saved 1. Still unset in staging: VITE_APP_NAME, VITE_DEV_BYPASS_AUTH. sf deploy will ask again.

In a script, in CI or with --yes it asks nothing, calls no API and writes what it found, including the stripPrefix guess, without runtime, migrate or databases:

$ sf init
Found 3 components:
  api1  web     api1  /api1  port 8080
  api2  web     api2  /api2  port 8080
  ui    static  ui    /
  Tip: api1's code never mentions /api1, so /api1/projects reaches it as /projects.
  Tip: api2's code never mentions /api2, so /api2/projects reaches it as /projects.
Wrote smallfield.json
$ sf init
smallfield.json already exists. Edit it by hand, or delete it and run sf init again.

sf deploy packs the current folder (skipping node_modules, .git, .env and anything in your .gitignore), uploads it, deploys it and prints the live address. See above.

When a project with that name already exists, sf deploy uses it only if this folder is linked to it: smallfield.local.json holds its projectId (written by sf init → Existing, or by the deploy that created it), you are a developer (developers only see projects they own), or you are one of its owners. An admin who is none of these (owners through a group included) can confirm with sf deploy --project <name>. Otherwise it stops:

A project named "helloworld" already exists and this folder is not linked to it. Pick another name in smallfield.json, or run sf init to link it. Admins: sf deploy --project helloworld.

Every other command that acts on the project in smallfield.json (secrets, env, status, releases, rollback, promote, maintenance, logs, run, runs, shared, template, db) makes the same check without creating anything, and takes the same --project <name>. Inside a git repo the local file is always git-ignored: added to the nearest .gitignore, or a new one in the folder.

Before packing, sf deploy checks the env secrets in smallfield.json. Any not set in the environment are asked for the same way (from .env, then hidden prompts); still missing means Nothing deployed. and exit 1. In a script, in CI or with --yes it prints the missing names with the command to set each and exits 1 before uploading:

1 secret not set in staging: VITE_MAP_KEY. Set it with:
  sf secrets set VITE_MAP_KEY --env staging
  In CI: printf %s "$VALUE" | sf secrets set VITE_MAP_KEY --env staging

sf secrets set|list|remove manages hidden values for your app. Without --value, set asks for the value with a hidden prompt (or reads it from a pipe). Only names are ever shown, never values. Changes reach your app on the next deploy.

$ sf secrets set GREETING --value hello
Saved. It reaches your app on the next deploy.
$ sf secrets list
GREETING
$ sf secrets remove GREETING
Removed. It disappears from your app on the next deploy.
$ sf secrets list
No secrets yet.

When some names are required (a project made from a template), list shows a table:

$ sf secrets list
NAME           REQUIRED  SET
SMTP_PASSWORD  yes       yes
REPORT_BUCKET  yes       NOT SET

sf secrets set and sf secrets remove without a name ask in a terminal: set asks for the name, remove lists your secrets to pick from. In a script they print Say which secret, for example: sf secrets set STRIPE_KEY (or remove) and exit 1.

On a template, removing a secret its forks use restarts those forks, so remove asks first (--yes skips the question; in a script nothing is removed unless you pass --yes, because a piped answer no longer confirms):

$ sf secrets remove STRIPE_KEY
Removing STRIPE_KEY restarts 2 fork environments. Continue? [y/N] y
Removed STRIPE_KEY from development. 2 forks are restarting without it (expense-london, expense-paris).

sf template publish [--security] [--notes "…"] publishes what runs live in the environment (development unless --env) as a version others can use from the console. A version looks like 1.4.3: three numbers. The first two are the line; the last is a fix inside it. --security updates every fork on an older version of the same line at once. Making a project from a template happens only in the console.

$ sf template publish 1.4.3 --security --notes "Fixes CVE-2026-1234"
Publishing expense-app 1.4.3 from development…
  published
Secrets: STRIPE_KEY (template, set for development), SMTP_PASSWORD (fork).
Security fix: 2 fork environments on 1.4 are being updated.
$ sf template publish 1.4.3
expense-app already has 1.4.3.

A template secret with no value for the environment prints a Warning: line first with the sf secrets set command to run. If publishing fails, the last line is the reason and the exit code is 1.

sf template versions lists the versions, newest first, with the first line of each version's notes.

$ sf template versions
VERSION  SECURITY  STATUS            FORKS  PUBLISHED   NOTES
2.0.0              published         1      2 days ago  New data model
1.4.3    security  published         2      1 hour ago  Fixes CVE-2026-1234
1.4.2              blocked by 1.4.3  0      3 days ago
1.3.5              published         1      9 days ago

sf status shows the latest release of the project named in smallfield.json.

$ sf status
helloworld / development
  status   live
  url      https://helloworld-dev.apps.example.com/
  release  3f9c0a1b  (12 minutes ago)
  ui    static  /
  api1  web     /api1  general on m7i.large
  api2  web     /api2  gpu on g6.xlarge (set by an admin; overrides smallfield.json)

The last column says where each web and job component runs (when the API knows about compute).

Before the first deploy it shows:

$ sf status
helloworld / development
  status   never deployed

sf logs [component] [--lines n] prints the recent output of one component, one line per line, as is. It shows 200 lines unless you pass --lines.

$ sf logs api1 --lines 50
<the last 50 lines api1 printed>
$ sf logs
Which component?
  1) ui
  2) api1
Number [1]: 2
<the last 200 lines api1 printed>

In a script, name the component: sf logs < /dev/null prints Say which component, for example: sf logs api1 and exits 1.

If anything is wrong, sf prints the reason and exits with code 1. For example, before signing in:

$ sf deploy
Run sf login https://<console host>/api first.

smallfield.json

{
    "project": "helloworld",
    "components": {
        "ui": {
            "kind": "static",
            "dir": "ui",
            "path": "/",
            "build": "npm run build",
            "output": "dist"
        },
        "api1": { "kind": "web", "dir": "api1", "path": "/api1", "port": 8080 },
        "api2": { "kind": "web", "dir": "api2", "path": "/api2", "port": 8080 }
    }
}
  • project: the name of your app. Lower-case letters, digits and dashes. It becomes part of the address and cannot end in -dev, -development, -staging or -production.

  • kind: static for a website built into files, web for a server that answers requests.

  • dir: the folder of the component, relative to smallfield.json.

  • path: where the component lives on the address. / is the main page, /api1 is .../api1.

  • port: the port a web component listens on.

  • build: the command that builds a static component. Optional: leave it out for a plain HTML site.

  • output: the folder the build writes the files to (static only). Defaults to dist when there is a build, and to . (the dir itself) when there is none.

  • stripPrefix: optional. By default the path is removed before the request reaches your server, so /api1/hello arrives as /hello. Set "stripPrefix": false to keep it. sf init asks and guesses from your code. Which one do I need?

    | Your code | /api/projects should arrive as | Set | | ----------------------------------------- | -------------------------------- | ---------------------- | | Hono/Express app.route('/api', …) | /api/projects | "stripPrefix": false | | Routes at / (app.get('/projects', …)) | /projects | nothing (default true) | | Next.js basePath: '/api' | /api/projects | "stripPrefix": false |

  • runtime: optional, "node" (default) or "bun". sf init asks about it in a terminal. With "bun" the image gets Bun 1.4.3 next to Node. Install still uses your lockfile, and start still runs npm start, so your start script can call bun.

  • migrate: optional, web only. A command run before each deploy with DATABASE_URL set, for example "npm run db:migrate". If it fails, the deploy fails and the old version keeps serving. Use npm run, not pnpm.

Sign-in page and the portal (optional)

Add a signIn block and showInPortal to set the app's sign-in page and portal listing from code:

{
    "project": "studio-finder",
    "components": { "web": { "kind": "static", "dir": "dist" } },
    "showInPortal": false,
    "signIn": {
        "heading": "Welcome to Studio Finder",
        "message": "Use your work email.",
        "showIcon": true,
        "methods": "microsoft_only",
        "brandColor": "#2e7d32",
        "radius": 8,
        "fontHeading": "inter",
        "fontSans": "inter",
        "panel": {
            "kind": "colour",
            "colour": "#0b2e13",
            "headline": "Find a studio",
            "text": "Book desks fast."
        },
        "helpLink": { "label": "Privacy", "href": "https://example.com/privacy" }
    }
}
  • Every key is optional. methods is inherit, email_only or microsoft_only; showIcon shows the app picture above the heading; panel takes kind (inherit or colour) plus optional colour, headline and text; radius is 0, 4, 8 or 12.
  • showInPortal: false hides a helper app from the portal.
  • Keys in the file win on every sf deploy. Keys you leave out keep whatever was set in the console, and the console shows the file's keys as "Set by smallfield.json".
  • No images here. Upload icons and panel pictures in the console.
  • sf init does not write these keys.

Frameworks

sf init recognises these. Each static component is served by nginx: unknown paths show index.html (so deep links and reloads work), /assets/, /static/ and /_next/static/ are cached for a year.

| Your app | Kind | output | Notes | | ------------------------------- | ----------------- | -------------------- | --------------------------------------------------------------------------- | | Plain HTML (no package.json) | static | . | No build. /about serves about.html. | | React or Vue with Vite | static | dist | build: npm run build. | | Create React App | static | build | | | Angular | static | dist/<app>/browser | | | Next.js with output: 'export' | static | out | Unknown paths show the home page (status 200). | | Next.js server (next start) | web | n/a | path is /. See below. | | Nuxt | static or web | .output/public | web when there is a start script (node .output/server/index.mjs). | | SvelteKit | static or web | build | adapter-static needs fallback: 'index.html'; web uses adapter-node. | | Astro | static or web | dist | web uses @astrojs/node in standalone mode. | | Remix / React Router | static or web | build/client | web runs react-router-serve. |

In a monorepo, sf init finds the apps listed in pnpm-workspace.yaml or in package.json workspaces (for example apps/web and apps/api). Shared library packages are skipped, because they have no start script and no framework. A shared package that another app depends on is skipped too, and ** in a workspace pattern matches one folder level only.

An app that is not at / must know its own address, because path is removed before the request reaches it. sf init prints a tip when it puts a static or framework component somewhere other than / (here two Vite folders):

$ sf init
Found 2 components:
  admin  static  admin  /
  web    static  web    /web
  Tip: web is at /web. Set your framework's base path to /web/ (Vite "base", Angular --base-href, Next basePath + "stripPrefix": false). See README.
Wrote smallfield.json
  • Vite: base: '/admin/'. Angular: ng build --base-href /admin/.
  • Next.js server at a sub-path: set basePath: '/admin' in next.config and "stripPrefix": false on the component.
  • Next.js server limits: next start runs read-only, so ISR and next/image optimisation cannot write .next/cache. Set images: { unoptimized: true }. output: 'standalone' is not supported.
  • Sample apps for each shape: helloworld/examples/.

Models and GPUs

A Python component whose requirements.txt or pyproject.toml names torch, tensorflow, tf-nightly, keras or jax looks like a model. sf init writes "compute": "gpu" for it and prints a cost tip. sf deploy on such a component without "compute" asks once in a terminal and saves the answer:

classifier looks like a model. Run it on a GPU (g6.xlarge, ~$0.80/h)? [Y/n]

In CI, with --yes, or when GPU is off or the cluster has no GPU types, it does not ask: it deploys on the default purpose and prints a note. Every deploy prints where each component runs, for example classifier runs gpu on g6.xlarge, with (set by an admin; overrides smallfield.json) when an admin moved it.

Update

npm i -g @thesmallfield/cli@latest

From source: cd cli && git pull && pnpm install && pnpm build. To move to a newer api (every api merge publishes 0.0.1-<short sha>): pnpm add @thesmallfield/[email protected]<sha> @thesmallfield/[email protected]<sha>.

Jobs and environments

  • sf run [job] starts a job now; in a terminal it lists the jobs of smallfield.json to pick from, and in a script it needs the name (Say which job, for example: sf run cleanup). sf runs [--job <name>] lists the latest runs. sf runs logs <runId> shows what a run printed.
  • sf run report --input '{"from":"2026-10-01"}' --secret-input-file key.json passes input to the run. The job reads --input from SF_JOB_INPUT and the file's JSON object from SF_JOB_SECRET_INPUT (- reads it from stdin). Input is at most 64 KB and shown with the run; the secret input is at most 16 KB, never shown again, and gone from the cluster once the run ends. Never print it in the job: logs are kept.
  • The environment for deploy, status, logs, secrets, run, runs, maintenance and template publish is the first of: --env <name>, SMALLFIELD_ENV, environment in smallfield.local.json (from sf init), your tenant's default environment (development on an older API).

Maintenance

sf maintenance on shows visitors a maintenance page for the environment; owners and admins can still open the app. It follows the same environment rules and needs the same permission as sf deploy.

$ sf maintenance on --message "Back at 3pm"
Maintenance is on for helloworld (development). Visitors see: Back at 3pm. Owners and admins can still open the app.
$ sf maintenance status
Maintenance is on for helloworld (development).
Message: Back at 3pm
Since: 2 hours ago
By: [email protected]
$ sf maintenance off
Maintenance is off for helloworld (development).

The message is up to 300 characters. sf maintenance alone is the same as sf maintenance status.

Environments

A project starts with one environment (usually development). Add others when you are ready.

$ sf env list
helloworld uses: development
Add another with: sf env add <name>
$ sf env add
Environment name (for example staging): staging
helloworld now uses staging. Deploy with: sf deploy --env staging
$ sf env add staging
The project "helloworld" already uses "staging".
$ sf deploy --env production
The project "helloworld" does not use "production" yet. Add it on the project page or run sf env add production.

Use it from Claude or ChatGPT

Small Field has an MCP server at https://appsadmin.example.com/mcp. It needs a developer or admin account, and every tool runs with your own permissions. (/api/mcp still works with a token for one release; use /mcp.)

Claude Code, with the token from sf login, no browser:

claude mcp add --transport http smallfield https://appsadmin.example.com/mcp \
  --header "Authorization: Bearer $(jq -r .token ~/.config/smallfield/config.json)"

Claude Code, signing in as yourself: leave --header out, run /mcp inside a session, sign in, click Allow.

claude mcp add --transport http smallfield https://appsadmin.example.com/mcp

claude.ai (also Claude Desktop and mobile, same account):

  1. Customize, Connectors, Add custom connector. On a Team or Enterprise plan an owner does it under Organization settings, Connectors, Add, Custom.
  2. Name Small Field, URL https://appsadmin.example.com/mcp. Leave the OAuth fields empty (the client registers itself). Add.
  3. Click Connect, sign in to Small Field (email code or Microsoft), click Allow.
  4. In a chat, press +, Connectors, turn Small Field on. Ask "Which projects do I have on Small Field?".

ChatGPT (a plan with custom connectors): Settings, Connectors, Create. URL https://appsadmin.example.com/mcp, authentication OAuth. Then sign in and click Allow the same way.

Renamed project file

sf login saves the project file names this install uses (for example appfoundry.json, then smallfield.json). The CLI reads the newest one it finds. If the file has an older name, an interactive command offers once to rename it (git mv when tracked) and reminds you to commit. In CI it never renames; it prints one line saying which file it used. sf init writes the current name.