Radial app

Command line

radial is the app from a terminal. It opens projects by path, name, or GitHub link, reads what Radial knows about a site, takes screenshots of the live preview, and scaffolds new sites. It is built for agents as much as for people: Claude Code, Codex, and Cursor find it on their PATH inside Radial and are told what it does.

Setup

Radial installs the command on first launch (/usr/local/bin, or ~/.local/bin when that isn't writable), and every agent terminal inside Radial has it on PATH regardless. The command talks to the running app; if the app isn't running, it starts it and waits. open -a Radial <folder> and dropping a folder on the Dock icon still work without the command at all.

Opening projects

radial .                              # this folder
radial ~/sites/acme                    # a path
radial open moment                     # a name Radial knows (project, folder, page title)
radial open acme/site                  # owner/repo: an existing clone, or a fresh one
radial open https://github.com/acme/site

A name is matched against the projects Radial knows: open ones, recent ones, the projects folder, and clones in ~/Radial. An exact match wins; a close call lists the candidates instead of guessing (a person picks by number, an agent gets the list and exit code 2). A GitHub link or owner/repo opens the clone you already have, wherever it is, and only clones into ~/Radial when there is none.

Opening never replaces your workspace: the projects you had open stay open and the new one is added alongside and brought forward. On the free plan the usual three-projects-at-a-time limit applies (exit code 5).

Reading a site

radial ls                              # open projects with their preview URLs
radial ls --all                        # plus recent ones
radial url [project]                   # the live preview URL (never guess a port)
radial status [project]                # git branch and changes, preview, live share
radial context [project]               # rules, .context docs, references, pages, preview URL
radial pages [project]                 # the routes the preview knows
radial comments [project] [--open]     # review comments pinned to pages
radial tokens [project]                # the site's CSS variables: value, type, modes, where used
radial shot [project] [route]          # full-page screenshot → PNG path in Downloads

context is the one to give an agent that needs to know a site: the project's AGENTS.md rules, every doc in its committed .context folder (design system, positioning, product reference), attached references as pointers, the page list, the preview URL, and how many comments are open. url and context answer from disk even when the app is closed.

Making and managing projects

radial new blog --template astro       # astro · next · html; opens when ready
radial new shop --template next --github
radial sleep [project]                 # stop its dev server, park its agents
radial wake [project]
radial reload [project]                # reload the preview (what ⌘R does)
radial restart [project]               # clean dev-server restart: fresh port, preview repointed
radial close [project] --yes           # --yes when agent terminals are live
radial focus                           # bring the app forward

restart is the fix for a stuck hot reload, when the served page no longer matches the files on disk. It never touches agent sessions, and it leaves a dev server started outside Radial alone (restart that one from its own terminal). Both actions are also in the project's menu in the sidebar rail.

Changing a site without an agent

radial fields ~/sites/acme /pricing     # the page's editable fields: f1 [Heading] h1: "Plans for every studio" …
radial edit text ~/sites/acme --field f1 --to "Plans that fit your studio"
radial edit text ~/sites/acme --find "Book a demo" --to "Book a call" --route /pricing
radial edit image ~/sites/acme --field f4 --file ~/Desktop/hero-v2.png
radial tokens set ~/sites/acme --brand "#8665f6"        # rewrite the token's declaration; --mode dark for a themed one
radial undo ~/sites/acme               # the app's own undo; `redo` puts it back
radial meta set ~/sites/acme og:title "Acme: invoicing for studios"
radial comments add ~/sites/acme --text "Tighten this headline" --route / --selector h1
radial comments resolve ~/sites/acme c1k2x
radial comments pull ~/sites/acme         # Vercel Toolbar comments on its deployments → Radial's comments (Vercel CLI 59.1+)
radial sync [project]                  # pull what teammates pushed; local edits are kept
radial publish [project]               # commit + push to staging (a preview deploy), after a real build
radial publish --to production --yes   # goes live: a terminal asks, scripts and agents say --yes
radial share [project] [--stop]        # a live share link for the running preview (Pro)
radial moments [project]               # version history; `moments record --label` and `moments restore <id> --yes`

These are the same deterministic engines the Content, SEO, and Comments panels use: no agent runs, nothing is guessed. fields lists a page the way the Content panel does, with an id per text or image; an edit that names a field is pinned to that exact element, so the same words on another page are never touched. Without a field, a text edit finds the exact current text in source; when it appears on several pages, pin it with --route or --file, otherwise it lists the candidates and exits 2 instead of picking one. publish runs the site's own production build first and refuses to push a tree that doesn't build (--no-gate skips that); a red build prints the log and a ready fix prompt you can hand to an agent.

Giving a site context back

radial context add ~/sites/acme positioning --text "# Positioning …"   # a .context doc every agent reads
radial context add ~/sites/acme brand-guide --file ~/Downloads/guide.pdf
radial refs add ~/sites/acme https://github.com/acme/brand                # a pointer agents fetch themselves
radial rules add ~/sites/acme "Never use em dashes in copy"                # one line in AGENTS.md

What an agent learns while working on a site, or on something that needed the site's context, goes back into the site the same way you would add it in the app: a committed .context doc, a reference link, a rule. From then on every session, in Radial or outside it, reads it through context.

Agents in a site's terminal

radial agent start ~/sites/acme "Rewrite the pricing FAQ from .context/positioning.md" --submit
radial agent wait pty7k2 --timeout 600  # returns bell · idle · exit · timeout, with the screen
radial agent send pty7k2 "Now do the same for the About page"   # a follow-up, submitted
radial agent output pty7k2 --lines 40   # the session's screen as plain text
radial agent list [project]
radial agent kill pty7k2 --yes
radial agent keep pty7k2 [--off]   # never parked; this Mac stays awake while it runs

agent start opens a new, visible Claude Code (or Codex or Cursor) session in that project's terminal inside Radial, exactly as if you had clicked New agent: you can watch it, take over, or stop it from the app. Without --submit the task is staged in the session for you to review and press Enter; with it the session starts working right away. Radial never runs agents out of sight, and a session started this way is your own CLI, using your own login.

agent wait reads the bell Claude Code rings when a turn completes or it needs attention, so it returns for both: read the screen it prints to tell "done" from "asking you something", then answer in the app or start another task. agent send continues a session with a follow-up, so a conversation can run from the phone: start, wait, read, send. This is how a general agent (the Home terminal, or Claude on your phone driving it) fans work out: one visible sub-agent per site, each in its own terminal. agent list marks each session working, waiting (it rang the bell after your last input), or idle, and ls shows which sites have sessions waiting on you, open comments, or unpublished changes. radial home shows Home and starts its agent from any terminal. agent keep keeps a session awake: Radial never parks it (project sleep, quitting, the two-hour idle limit) and your Mac won't idle-sleep while it runs, which is what a session you drive from your phone needs; --off releases it.

For agents

• Inside Radial, every Claude Code session is told these verbs, and each project's AGENTS.md carries a managed Radial CLI section for Codex and Cursor. Outside Radial, radial --help is the reference.
• Prefer a path over a name when you know one, and read the preview URL with radial url (or .radial/dev.json) instead of guessing a port.
• --json prints exactly one JSON object on stdout with progress on stderr, for tools that parse the result.
• Anything outward-facing or destructive needs --yes: publishing to production, restoring a moment, ending a session, closing a project with live agents. Without it the command refuses with exit code 6 and says so.
• radial mcp serves the same verbs as MCP tools so Claude Desktop, Cursor, and Codex can call Radial directly. See MCP.

Exit codes and flags

Flags: --json, --no-wait (return as soon as the app has queued an open), --yes, --timeout <seconds>. The command follows the app it sits next to: the installed app from your PATH, or the dev flavor from a source checkout.