@freeappstore/cli

The fas CLI for FreeAppStore creators. Scaffold, check, publish, and manage your free apps.

Install

npm i -g @freeappstore/cli

Requires Node 22+.

Quick start

fas login              # GitHub device-flow auth
fas init my-app        # scaffold from the standalone template
cd my-app
pnpm install && pnpm dev
fas check              # compliance checks
fas publish            # provisions repo + hosting + DNS
git remote add upstream https://github.com/freeappstore-online/my-app.git
git push upstream main # follow the commands printed by fas publish

After the first successful code push and deploy, live at https://my-app.freeappstore.online.

Commands

fas login

Sign in with GitHub via the device-authorization flow. Opens a browser to authorize the CLI, then exchanges the GitHub token for a platform session token. Both are persisted to ~/.fas/config.json (mode 0600).

fas login

fas logout

Clear the cached platform session token.

fas logout

fas whoami

Print the GitHub login of the currently signed-in user. Exits non-zero if not authenticated.

fas whoami
# @yourname

fas doctor

Run local health checks: Node version, git, pnpm, config file, signed-in state, and API reachability.

fas doctor --offline
fas doctor --offline --verify --artifact
fas doctor --offline --json

fas init <app-id>

Scaffold a standalone or connected app from the same canonical starter foundation used by the builder. The presets share their routing, PWA, styling, and capability files; connected adds a private draft example while leaving public screens reachable. Games are scaffolded and published with the separate fgs CLI. The command substitutes app identity and creates the first git commit.

fas init my-app                        # default: standalone template
fas init my-app --template connected   # uses platform backend (KV, rooms, etc.)

fas check

Run compliance checks against the app in the current directory (or --dir). Checks include: no tracking SDKs, no payments, no ads, brand fonts present, no brand token overrides, PWA manifest valid, bundle size under limit, and no leftover APPNAME placeholders. Exits non-zero on hard failures.

fas check              # check cwd
fas check --dir ../my-app

fas publish

Provision and publish an app to FreeAppStore. Runs compliance checks, authenticates, creates a GitHub repo + R2 hosting route + storefront registry entry via the admin Worker, and injects a deploy workflow.

By default, publish is interactive — it asks for category, type, oneliner, and demo URL. Skip prompts by passing flag values; combine with --yes to fail fast in CI rather than hang on a missing field.

fas publish                          # interactive
fas publish \
  --name my-app \
  --category Utilities \
  --type standalone \
  --oneliner "Does the thing." \
  --yes                              # non-interactive (CI)

The generated deploy.yml is the same one fas init writes. It has two jobs: build (install, typecheck, tests, build, pinned @freeappstore/cli validation, pinned code-health scan — no secrets) and deploy (needs: build; downloads the build artifact and syncs it to R2 — runs no project code). Every action is pinned to a commit SHA and every npx to an exact version.

fas list (alias fas ls)

List apps you have published. Shows app id, category, live URL, and creation date.

fas list               # human-readable table
fas list --json        # full JSON with per-app commit history
fas list -v            # verbose — show last 3 commits per app

fas logs <app-id>

Show recent GitHub Actions deploy runs for an app. Shows status, timestamps, and links to failed runs.

fas logs calculator

fas secret set|list|rm

Manage server-side encrypted API keys for an app. Secrets are stored on the platform and injected at runtime via the proxy. Values are encrypted at rest; list only shows names, never values.

fas secret set OPENWEATHER_KEY --from-env OPENWEATHER_KEY
printf '%s' "$OPENWEATHER_KEY" | fas secret set OPENWEATHER_KEY
fas secret set OPENWEATHER_KEY                  # hidden interactive prompt
fas secret list                                  # list secret names
fas secret list --json                           # machine-readable
fas secret rm OPENWEATHER_KEY                    # delete a secret

All subcommands accept --app <id> to specify the app explicitly. If omitted, the app id is derived from the name field in the current directory's package.json.

fas proxy allow|list|deny

Manage the URL allowlist for the per-app secret-injecting proxy. The proxy intercepts outbound API calls from your app and injects the appropriate secret (as a query param, header, bearer token, or OAuth2 client credentials exchange) so that API keys never reach the browser.

# Allow the proxy to inject OPENWEATHER_KEY as a query param when calling the API
fas proxy allow "https://api.openweathermap.org/" \
  --secret OPENWEATHER_KEY \
  --inject "query:appid"

# Inject as a Bearer token
fas proxy allow "https://api.example.com/v1/" \
  --secret EXAMPLE_TOKEN \
  --inject bearer

# OAuth2 client credentials flow
fas proxy allow "https://api.spotify.com/v1/" \
  --secret SPOTIFY_CLIENT_ID \
  --secret2 SPOTIFY_CLIENT_SECRET \
  --inject oauth2_cc \
  --token-url "https://accounts.spotify.com/api/token"

# List current rules
fas proxy list
fas proxy list --json

# Remove a rule
fas proxy deny "https://api.openweathermap.org/"

allow flags:

fas screencheck

Build the app and run a headless Chromium browser at every reference viewport in the device matrix (portrait + landscape, from iPhone SE to iPad Pro). Reports whether the layout fits without scrolling or clipping, and computes device coverage percentages. Requires Playwright as a dev dependency in the app project.

fas screencheck                       # build + test local dist
fas screencheck --skip-build          # test existing dist without rebuilding
fas screencheck --screenshots         # save a PNG per viewport to ./screencheck-out/
fas screencheck --url https://my-app.freeappstore.online  # test a live deployment

fas quality [app-id]

Show the VCQA (VibeCode QA) code quality report for an app. Fetches the latest report from the platform API and displays the composite score (0--100), letter grade (A--F), per-check breakdown, and top issues.

If app-id is omitted, the command auto-detects it from the current directory's package.json name, a *.freeappstore.online reference in CLAUDE.md, or the directory basename.

fas quality                  # auto-detect app id from cwd
fas quality timer            # explicit app id
fas quality timer --json     # raw JSON for scripting

Configuration

~/.fas/config.json (mode 0600) holds the GitHub OAuth token + the platform session token. fas logout deletes both.

Brand and UI rules (mandated)

Every app and game on the platform shares the same visual language — colors, fonts, spacing — so the storefront and detail pages stay predictable. fas check enforces:

fas publish auto-runs fas check and aborts on hard failures. The platform also checks the built artifact before making a deploy live.

How fas publish works

1. Compliance gate: runs the same checks as fas check. Hard failures abort.
2. Auth check: confirms a valid session token (re-login if expired).
3. Provision: POSTs to the platform API, which calls the admin Worker via service binding. Admin creates an empty GitHub repo, inserts a D1 hosting route (subdomain → R2 prefix), and appends the app to the storefront registry.
4. Deploy workflow: injects .github/workflows/deploy.yml locally if missing, so the first git push triggers an R2 deploy. An existing file that differs is reported, not replaced — pass --update-workflow to regenerate it.
5. Ownership: records the app in the platform DB so fas list returns it.
6. Output: prints the live URL, repo URL, storefront listing URL, and the git remote add + git push commands to populate the new repo.

If provisioning is unavailable, the command reports the error and exits. Nothing is queued and no submission form opens. Retry after checking the platform status; --issue is not a supported flag.

For AI Agents

Building with Claude Code, Cursor, or another AI tool? Connect the MCP server for tool-based access:

{
  "mcpServers": {
    "freeappstore": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.freeappstore.online/mcp"]
    }
  }
}

Or read the full platform guide: freeappstore.online/skills.md

License

MIT.

Migrate an existing app to token utilities

Run fas migrate tailwind-tokens --dir <app-repo> to preview a unified diff and per-file counts. Add --write to apply it. The command scans web/src, adds missing Tailwind theme mappings for defined FAS tokens, and rewrites class attributes and cn/clsx/classnames calls while preserving variants and opacity. Radius and shadow mappings use rounded-fas, rounded-fas-sm, and shadow-fas.

Banned aliases are resolved from the app's own CSS; conflicting light/dark definitions, cycles, and unknown tokens are left in place and reported. Review the remaining CSS rules, hex colours, dark overrides, and inline-style counts in the report. Run the app build after applying the migration. Re-running the command is a no-op once migrated. This command does not convert static inline styles or add SDK @source directives.