The sf CLI

sf is the developer interface to Spikefrost. Everything the desktop app and the web console do, it does — plus scripting, CI, and use from your own coding agent.

Install

curl -fsSL https://edge.spikefrost.com/sf/install.sh | sh

macOS, Linux, and WSL. The installer fetches a private Node.js runtime if your system doesn't have a recent one, so there's no version to manage. Open a new terminal afterwards, then:

sf --version

If you installed the macOS desktop app, you already have sf — it ships with it and keeps it updated.

Authenticate

Interactive, for humans:

sf login          # prompts for email, then the 6-digit code
sf whoami

Non-interactive, for scripts and agents — two steps so something else can supply the code:

sf login start --email you@example.com --json
sf login complete --code 123456 --json

For CI and long-lived automation, use an API key instead:

sf set-api-key <key>

sf whoami prints the account, the active team, the platform environment, and how you authenticated. It's the first thing to run when something behaves unexpectedly.

Teams

Every command runs in the context of one active team:

sf teams                 # * marks the active one
sf team use "My Team"    # switch it
sf apps list --team <id> # or override per command

Apps and checkouts

Create an app and check it out in one step:

sf app create "My First App"
cd my-first-app

Or check out an app that already exists:

sf apps list
sf app checkout <appId>

A checkout contains .spikefrost/project.json, which binds the folder to its app. Commands run inside a checkout need no --app — sf figures it out. Outside a checkout, or to target another app, pass --app <appId>.

The working loop

sf vcs status                    # local changes, and whether the cloud moved
sf vcs pull                      # merge the cloud's head into your tree
# ...edit files, or let your coding agent do it...
sf build                         # compile + typecheck + platform checks
sf deploy                        # ship it
sf vcs commit -m "what and why"  # record the snapshot

Two habits that prevent most trouble: pull before you start (cloud agents and teammates commit to the same app), and commit coherent chunks rather than one giant snapshot at the end. Full semantics in Version control and Build and deploy.

Working with a coding agent

The intended developer setup is sf plus a coding agent in the same folder:

cd my-first-app
claude        # or: codex

Because the terminal is inside a checkout, the agent's sf calls resolve to the right app automatically. The platform also maintains CLAUDE.md and AGENTS.md in the checkout — generated instructions that teach the agent this app's conventions. They're refreshed when the CLI updates, so don't hand-edit them; put your own durable decisions in DECISIONS.md instead, which is versioned app content.

Two commands exist specifically for agents:

sf docs                        # project structure, build/deploy rules, local workflow
sf skills list                 # the platform's operating instructions
sf skills get web_development  # load one

What you'll use most

Data

sf d1 schema                                # dump the DDL
sf d1 select "SELECT * FROM leads LIMIT 10" # read-only
sf d1 execute "UPDATE leads SET ..."        # mutating
sf d1 migrate list                          # migration state
sf d1 history                               # point-in-time recovery bookmarks

Observability

sf logs --since 6h --errors        # request logs, filterable
sf deployments                     # deploy history
sf deployments logs <id> --follow  # tail one deploy's events
sf durable-objects                 # deployed vs declared DO classes

Configuration

sf set_worker_secret --secretName STRIPE_KEY --secretValue sk_live_...
sf list_worker_secrets
sf add_custom_domain --customDomain www.example.com
sf list_custom_domains
sf assets upload ./hero.png --path img/hero.png

Agents and jobs

sf agents list
sf jobs start --goal "Summarize yesterday's unanswered threads"
sf routines list
sf models                          # model ids your team can use — never guess these

Conventions worth knowing

• --help is schema-driven. sf <command> --help prints the real required and optional parameters. Prefer it to guessing.

• --json works everywhere. Machine-readable output for scripts; also the fastest way to see a command's full response.

• Environments. --env <name> on environment-sensitive commands (deploy, logs, d1, analytics, deployments), or SF_APP_ENVIRONMENT=<name> to scope a session. Explicit --env wins.

• Platform operations have dedicated subcommands. sf agents, sf connectors, sf d1, sf routines, sf skills, sf queues. Use those.

• find_tools is for third-party capabilities only — the integrations your agents call:

  sf find_tools --query "send email"
  sf get_tool_schema --tool gmail#send_email
  sf execute_tool --tool gmail#send_email --json-params '{"to":"..."}'
  

  Searching it for platform operations returns unrelated results.

• REST fallback. Anything not yet wrapped:

  sf api get /apps
  sf api get /apps/<appId>
  

Next

• App anatomy — what's in the checkout you just made.
• Build and deploy — what sf build and sf deploy actually do.
• Environments — staging, promotion, and rollback.