UlikaDocs
Open Ulika

Getting started

  • Ulika documentation
  • How Ulika works
  • Requirements
  • Quickstart

Connect a site

  • Connect from the dashboard
  • Connect with the CLI
  • Connect with an AI agent
  • Approving a connection
  • Private previews
  • The GitHub App
  • Connect Vercel

Integrations

  • GitHub integration
  • Vercel integration
  • Netlify
  • Claude Code
  • Codex
  • MCP tools

Editing

  • The editor
  • The style panel
  • Sections and pages
  • Mobile preview, autosave and drafts

Publishing

  • Publish your changes
  • History and restoring a version
  • When a publish fails

Team

  • Team roles
  • Inviting people

Projects

  • Project settings
  • Delete a project
  • Website code

Troubleshooting

  • Needs attention reasons
  • Vercel problems
  • GitHub problems
  • CLI errors and exit codes
  • Frequently asked questions

Security and privacy

  • Security and privacy overview

CLI

  • CLI reference
  • CLI changelog

CLI

CLI reference

Every Ulika CLI command, option, environment variable, exit code and JSON output, verified against the CLI source (version 0.7.1).

Last updated October 25, 2026

This is the complete reference for the ulika command line, version 0.7.1. For a guided walkthrough, start with Connect with the CLI; for errors, see CLI errors and exit codes.

Running the CLI#

The CLI is served by Ulika itself, so there is nothing to install first. It needs Node.js 20 or newer.

bash
npx -y https://ulika.co/cli/ulika-cli-0.7.1.tgz connect https://your-site.com

Use the versioned address (ulika-cli-<version>.tgz) rather than https://ulika.co/cli.tgz: npx caches a tarball by its address, so an unchanging address keeps running whatever copy a computer fetched first. https://ulika.co/cli/version.json reports the current version. To get a permanent ulika command, run npm i -g https://ulika.co/cli.tgz.

Throughout the docs ulika stands for either form.

Commands#

CommandWhat it does
ulika connect <url>Connect one site from any computer. Ulika finds the repository through its GitHub App and prepares the connector.
ulika connect [sites]Connect many sites with one approval: every site Ulika can see, a list of URLs, or a list of repositories.
ulika preview <url> --yesBuild the current draft of a connected site on its own branch and print the preview address once it is read back. Nothing is published.
ulika init [siteUrl]Inside a website's checkout: read it directly and connect it. Anywhere else with a URL: the same as connect.
ulika loginAuthorise this computer once, in the browser.
ulika logoutForget this computer's stored authorisation.
ulika whoamiShow the workspace and user this computer is authorised as.
ulika scanScan a checkout and print what Ulika would learn. Sends nothing.
ulika statusRead ulika.config.json and report the connection.
ulika mcpRun as an MCP server over stdio, for AI coding agents.
ulika codex installAdd Ulika (MCP server and skill) to Codex. ulika codex uninstall removes it.
ulika link <token>Join a project that already exists in Ulika, with a pairing token.
ulika versionPrint the version.
ulika helpPrint the help.

Details for each command follow.

connect#

Two forms. ulika connect <url> connects one site. ulika connect with --all, --urls or --repos connects a list. Both ask for one browser approval per computer, then Ulika does the work on its servers. The command also accepts one or more positional addresses (ulika connect https://a.com https://b.com), and a positional owner/name is treated as a repository.

Ulika refuses its own address and its own repository, with the reason this-is-ulika.

A single connect <url> takes the local path (your checkout, vercel and gh) instead of Ulika's GitHub App only when you asked for it: you passed --local, --dir, --scope, --import-only, --activate, --confirm-domain or --dry-run, or the current directory is a checkout that already serves that address. Everything else goes through the GitHub App.

The approval step. The first run opens one approval page in your browser, and what it does depends on the situation:

SituationWhat happens
Events, in orderA new run prints the preview (site_preview), then the browser steps (browser_plan), then the link and code (approval_required). Find them by name.
The pageIt leads with Continue with GitHub, creates the account and a workspace named after the site on first use, and checks the GitHub App installation live.
A repository pickIf the page cannot tell which repository serves a site, you pick one there. A pick applies to this run only, and only to the first site that is not paired. --repo always wins over a repository picked in the browser.
A site already pairedA site paired with --repo is sent to the page as already paired (pairedSites), so the page never asks for it.
No terminalThe preview, the steps and the link go to standard error.
On WindowsThe browser opens with the system start command. The link is always printed, so you can copy it if nothing opens.
--waitKeeps waiting for approval and for Activate even without a terminal. Cannot be combined with --no-wait.
--no-waitPrints the steps and the link, never opens the browser and exits with code 22.

init#

The original command. In a directory that looks like a website (it contains package.json, ulika.config.json, index.html, next.config.ts, next.config.js, astro.config.mjs, svelte.config.js or nuxt.config.ts), a bare ulika runs init. Anywhere else a bare ulika prints the help, so it never scans a home folder by accident.

init stays the local-checkout command. Given a site address that the current directory does not serve, it hands over to connect. With no site, no checkout and no --dir, in a terminal it asks Site URL to connect (https://your-site.com):; without a terminal, or with --json, it exits with code 2 and tells you to run ulika connect https://your-site.com.

preview#

ulika preview <url> --yes builds what is in the site's editor right now, without publishing it. It needs --yes because the draft is unpublished: it is committed to a branch of the site's repository and stays in that repository's git history, so if the repository is public anyone can read it. Without --yes it sends nothing, says so and exits 2. The server reports whether the repository is public, and the command warns loudly when it is. The push also triggers the repository's own push workflows (CI, and any deploy configured for every branch). Ulika commits the draft content (the same one-file commit a publish makes) to ulika/preview-<id>, a branch of its own that is created again only when the draft changes, waits for the host to build that commit, reads the draft back from the preview and prints the preview address. The default branch is never touched, no pull request is opened, no draft is finalized and no release is recorded, so the live site and the publish history stay as they were. While the connector pull request is still open, the preview is built on top of the connector branch.

It needs a site that is already connected and delivers content through git, and the sign-in ulika login gives (or ULIKA_TOKEN). An agent approval is not enough: an agent may connect sites but never read drafts or publish. Without the sign-in the command exits 11 and starts none. Your role must be allowed to publish and the project must be inside the projects you can reach. It sends the site address, and --repo when you pass it. --wait-timeout <min> (1 to 60, default 10) sets how long to wait for the build.

It never claims a pass it did not read back. Exit 0 means the preview serves exactly this draft. Exit 30 means it is not proven: the host built it but the preview is private, nobody can observe the build (no hosting connection, or no permission to read statuses), or the wait ran out; the branch name, commit SHA and branch link are always printed, any preview address is labelled (not verified), and when the cause is that Ulika's GitHub app has not been given read access to statuses, checks or deployments, the permissions page of that installation is printed too. Exit 31 is a failed or canceled build, with the deployment link. Exit 32 means nothing was previewed (the site is not connected, fetches its content at build time, already serves this draft, the role cannot publish, the draft is invalid (for example a collection below its minimum, with the editor's sentence), the connector pull request was closed or undone, or the base branch no longer exists). --json prints a consent_required error without --yes. With --json it prints preview.branch (branch, commitSha, reused, base, branchUrl) and ends with one preview event (outcome, status, previewUrl, previewVerified (false when a previewUrl is not proven), branch, commitSha, branchUrl, logUrl, reason, permissionsUrl and missingPermissions when permissions are the cause, message, exitCode).

login, logout, whoami#

login starts the browser approval even when something is already stored. logout removes the stored authorisation for one Ulika address. whoami shows who this computer is authorised as (workspace, user, role, since, config file). If the ULIKA_TOKEN environment variable is set, whoami reports that source instead, and logout reminds you that the variable is still used first.

scan and status#

scan reads the project and prints what it found: framework, repository, routes, a count by kind (text, images, links, SEO) and a sample of fields with their file and line. It never touches the network. status reads ulika.config.json and reports the project id, site, number of fields, when it was imported, and the installation state.

codex#

ulika codex install and ulika codex uninstall. See Codex.

mcp#

Runs the MCP server on standard input and output. See MCP tools. Nothing else may print to stdout while it runs.

link#

ulika link <token> joins a project that already exists in Ulika. The token starts with ovl_live_, is single use and short lived. It scans the checkout, prints exactly what would be sent, asks for confirmation (skipped with --yes), sends only the derived manifest and writes ulika.config.json. init or connect is the documented path and needs no token.

Options#

Each option appears once. Short forms are listed beside their long form. Options that take a value accept either --name value or --name=value; a value cannot start with -. Boolean options never take a value. An option the CLI does not know is an error (exit code 2), never silently ignored.

OptionValueApplies toDescription
--help, -hnoneallPrint the help and exit 0.
--version, -vnoneallPrint the version and exit 0.
--jsonnoneall commands that reportMachine-readable output, no prompts, no colour. One JSON object for most commands; one JSON line per event for a batch connect. See JSON output.
--server, -s<origin>allThe Ulika address. Default https://ulika.co, or the value of ULIKA_SERVER. For connect it must be an https origin with no path, query or credentials (plain http is accepted only for localhost).
--url, -u<siteUrl>init, connect, linkThe deployed site address. Accepts acme.com. Give it once, either positionally or with this option.
--repo<owner/name>connect <url>, init <url>Name the GitHub repository that serves the one address you gave. Must be a single owner/name.
--dir, -d<path>init, link, scan, statusThe project root. Default: the current directory. A directory that does not exist is an error. Passing it also selects the local path for connect <url>.
--scope<team>init, connect <url> (local path)The Vercel team to use when resolving the domain. Selects the local path.
--localnoneconnect <url>, init <url>Resolve the address with this computer's checkout, vercel and gh instead of Ulika's GitHub App.
--dry-runnoneinit, connect <url> (local path), link, codexScan and print what would happen. Writes nothing. For codex, shows what would change in the config. connect <url> reports what a real run would do, with its exit code; when this machine cannot resolve the source it asks Ulika's server, which receives the site address and --repo. It needs an approved machine and never starts an approval (exit 22: run connect <url> --no-wait and approve the link first), and it reports on one site at a time (several sites exit 2).
--import-onlynoneinit, connect <url> (local path)Import the content without installing the connector. Cannot be combined with activation.
--activatenoneinit, connect <url> (local path)Merge a connector whose preview has been verified, then verify production. Use it only after reviewing the pull request.
--confirm-domainnoneinit, connect <url> (local path)Confirm that the address you gave should be associated with a repository that advertises a different domain. Without it, a script exits with code 25.
--allnoneconnectEvery site in the GitHub repositories Ulika can see. Cannot be combined with a list of sites or repositories.
--urls<list>connectA comma- or space-separated list of site addresses, or the path of a file with one per line. A # starts a comment in a file.
--repos<list>connectA comma- or space-separated list of owner/name repositories, or a file. A batch list only; for one address and its repository use the single-repository option instead.
--resume<batchId>connectFollow a batch that is already running. Cannot be combined with a list of sites or with the all-sites option.
--review-firstnoneconnect, initThe default, accepted and ignored. By default Ulika opens a pull request and merges nothing until you activate it.
--auto-mergenoneconnect (batch path)With automatic merge, Ulika merges the connector once your host's build passes, checks your live site, and undoes its own merge if the production build fails. Single-site connect <url> and init refuse it: review the pull request, then run again with --activate.
--no-waitnoneconnect, loginPrint the approval link and exit with code 22 instead of waiting for approval. For connect it also means do not wait for you to click Activate.
--wait-timeout<min>connect, previewconnect: how long to wait for you to click Activate, 1 to 120 minutes, default 15. preview: how long to wait for the preview build, 1 to 60 minutes, default 10.
--no-browsernoneconnect, login, initNever open the approval page automatically.
--reopennoneconnect (batch path)Open a new connector pull request where the last one was closed on GitHub. Without it, Ulika never opens another by itself after a person closed one, and stops with pull-request-closed. A pull request Ulika closed itself (an outdated one it replaced) is started again without it.
--reapprovenoneconnectAsk a person to approve this computer again. Required weekly for organisation repositories.
--checknoneconnectRead only. List everything that would stop this site from connecting, all at once, and change nothing. Needs exactly one site address.
--yes, -ynoneconnect (all sites), preview, link, codex install, initFor an all-sites connect: you already agreed to the list. preview: you agree that the unpublished draft is committed to a branch of the repository and stays in its git history (readable by anyone when the repository is public). link: skip the confirmation question. codex install: trust a non-official Ulika address. init never asks, so it has nothing to skip.
--no-skillnonecodex installOnly edit config.toml; do not install the Ulika skill.
--forcenonecodex install, codex uninstallEdit or remove a ulika entry in config.toml that Ulika did not create. A backup is saved first.

Combinations the CLI rejects#

These end with a usage message and exit code 2.

  • A single address with several repositories: --repos is only for batches.

  • --repo together with a list, with --all, or with --dir on init.

  • A site address given both positionally and with --url.

  • --resume together with --all, --urls, --repos or any site.

  • --import-only together with --activate.

  • A one-site local connect together with the batch approval options. Single-site local connect prepares a reviewable pull request; batch approval options do not apply to it.

  • A --wait-timeout outside 1 to 120.

Environment variables#

VariableUsed byEffect
ULIKA_SERVERallThe Ulika address when no server option is given. Default https://ulika.co.
ULIKA_TOKENinit, whoami, logout, MCPA workspace token (starts with ovl_wt_). Wins over anything stored on the computer, so a scripted run is never surprised by whoever last signed in. For connect, a value starting with ovl_at_ is used as the agent token and skips the approval; a workspace token there is ignored.
ULIKA_NO_BROWSERconnect, loginSet to 1 to never open the approval page automatically.
CI, SSH_CONNECTION, SSH_TTYconnect, loginWhen set, the approval page is not opened automatically.
DISPLAY, WAYLAND_DISPLAYconnect, loginOn Linux, the browser is only opened when one of these is set. macOS and Windows always try (unless the cases above apply).
NO_COLORallTurns colour off. Colour is also off when output is not a terminal.
CODEX_HOMEcodexThe folder that holds Codex's config.toml. Default ~/.codex.
ULIKA_VERCEL_BYPASSlocal initA Vercel protection bypass secret used to read a protected connector preview.

Two more variables live on your host, not in your terminal: ULIKA_CONNECTOR_TOKEN and the older ULIKA_BUILD_TOKEN. Ulika sets them on your Vercel project so your site's build can fetch published content; the build reads ULIKA_CONNECTOR_TOKEN first. You normally never touch them.

Exit codes#

Exit codes are stable, so a script can branch on them.

CodeMeaning
0Success. For connect, at least one site is live and none failed.
1An unexpected failure.
2Usage error: unknown option, missing value, bad combination, bad address or repository, no project here, an unknown batch id, or preview without --yes.
3link: the pairing token does not exist.
4link: the pairing token expired.
5link: the pairing token was already used.
6link: the project the token belongs to no longer exists.
7The server rejected the request or manifest (bad request), or the repository does not match.
8Protocol mismatch: this CLI is too old or too new for the server.
9The server failed. Try again.
10The server could not be reached.
11Not authorised: no approval on this computer, the approval was denied or expired, or the token is not valid.
12This computer's authorisation was revoked.
13Forbidden: this account may not do that in that workspace.
14The scan found no editable content.
15init or local connect: the project is configured, but the connector pull request still needs review or activation.
16init or local connect: the project is configured, but installing the connector did not finish.
20connect: no site went live and none failed. This is not an error: Ulika is waiting for you, most often to merge the connector pull request (the report names it and links it; the reason is pull-request-awaiting-merge). Every site needs a person, including a site waiting for Vercel (the reasons vercel-not-connected, vercel-wrong-account, vercel-token-invalid, vercel-unavailable). --check exits 20 too and reports its blockers by finding code in blockers[], among them vercel-not-connected, vercel-project-not-found, vercel-no-permission, vercel-token-invalid, vercel-not-git-linked, vercel-linked-to-other-repository and vercel-project-held-elsewhere. vercel-not-connected and vercel-token-invalid are spelled the same in both layers. Connect Vercel within 24 hours and it continues by itself; follow it with --resume <batchId>.
21connect: at least one site really failed. Waiting for Vercel is never a 21.
22connect: approval is still required (no-wait, or nobody approved in 15 minutes).
23connect with all sites: the list was not confirmed. Nothing was written.
24connect: this agent's 24-hour site cap is spent.
25Local connect or init: the repository advertises a different domain; confirm the domain association.
26init, connect: Ulika has no installer for this site's framework (anything but React with Vite or Create React App, and Next.js App Router), found right after the scan. Nothing was created in Ulika: no project, no ulika.config.json. --import-only exits 26 too. --dry-run exits 26 too. connect exits 26 when nothing is live and every failed site was refused for this reason.
30preview: the preview is not proven. The host built it but it is private, the build cannot be observed, or the wait ran out. The branch link is printed and no pass is claimed.
31preview: the host's build failed or was canceled.
32preview: nothing was previewed (not connected, content fetched at build time, nothing different from what is served, or a role that cannot publish).

Each code is explained, with a fix, in CLI errors and exit codes.

JSON output#

--json turns off the spinner, colour and prompts. Everything is written to standard output; exit codes are the same as without it.

One object#

These commands print a single pretty-printed JSON object.

CommandKey fields
init, local connect <url>ok, status (active, installation-pending, imported, handoff, dry-run, or a failure status), projectId, projectName, projectUrl, editorUrl, editorNote (a sentence saying the editor is a preview until the connector is activated, or null once it is active), approved, needsReview, summary, scan, configFile, installation, and result.
scanok, status: "scanned", project, summary, routes, scan.
statusok, status, installation, config, configFile; or status: "not-connected" with reason.
linkok, status: "linked", projectId, projectName, accepted, reviewUrl, summary, scan, configFile.
login, whoamiok, status (signed-in, auth-required, not-signed-in), server, workspaceId, workspaceName, userName, role, source. In JSON mode login never starts a browser approval.
logoutok, status (signed-out or not-signed-in), server.
versionok, version, protocolVersion.
codex install and codex uninstallok, status, and the paths touched.

In init and local connect, result separates what happened: requestedDomain, repository (identified, fullName, branch), project (configured, id, name, url), domain (connected, status), pullRequestUrl, fieldsToReview (count, url) and nextAction. Exit code 0 means configuration finished, not necessarily that production is live: result.domain.connected is the authoritative check. nextAction is one of none, review-fields, install-connector, review-pull-request-and-activate, wait-for-preview-and-retry, verify-production-domain, finish-in-browser, none-unsupported-framework, resolve-source, confirm-domain-association, choose-repository-or-domain or select-the-matching-repository.

A failure prints ok: false, status, code, error, hint, projectUrl and result.

One line per event#

connect through the GitHub App (a single address or a batch) prints newline-delimited JSON: one object per line, each with an event field, as things happen. The last line is always report on success and error on failure. Find an event by its event name, never by its position: approval_required is usually not the first line, because site_preview and browser_plan can come before it.

eventWhenFields
site_previewBefore browser_plan, once per site for the first two distinct sites, only when a new approval code is about to be requestedstatus (ok, limited or skipped), site; with ok: finalUrl, reachable, pages{count,sample[],truncated}, framework{value,confidence}, hosting{value,confidence}; with limited: retryAt, scope; with skipped: reason
browser_planJust before approval_required, when the code is new or the browser is openingsteps[], expiresInMinutes
approval_requiredThis computer has no approval yeturl, code, expiresAt, expiresInMinutes, browserOpened
approvedThe approval arrivednone
batchThe batch started or was picked up againbatchId, resumed, sites
retryingUlika answered busy and the CLI is backing offstatus, inSeconds
confirmation_requiredThe all-sites list is waiting for your agreementbatchId, count, sites[] (siteId, site, repo, siteUrl), hint, exitCode 23
confirmedYou confirmed the all-sites listbatchId, sites
site.*A site changed stepid, at, siteId, site, plus that event's own fields. site.committed carries branch, outcome (created, reused or replaced), connectorVersion, and when they apply replacedPull and newerAvailable; site.pr_open carries pullUrl, number, outcome (opened or reused), connectorVersion and newerAvailable
activation_requiredA site waits for you to click ActivatesiteId, site, action (label, url, optional secondary), waitingMinutes
verifyingA merge was seen (yours on GitHub, or Ulika's): nothing is asked of you, and the run keeps following until your live site serves the connectorsiteId, site, minutes
waitingStill waiting for Activate, or still verifying the live site (every 30 seconds)reason: "activation" or "verification", minutesLeft
activation_timeoutThe wait for Activate endedminutes
verify_timeoutThe follow of a merged site ended before the live site served the connectorminutes
preflightResult of the read-only check (--check)site, repository, ready, blockers[], warnings[] (each { code, message, fix: { label, url } })
reportAlways last on successbatchId, summary, live[], attention[], failed[], pending[] (each with state, words and next: what the site is doing and the one next step), exitCode
errorAlways last on failurecode, error, hint, exitCode

The site.* kinds the CLI knows are site.queued, site.resolved, site.discovered, site.imported, site.planned, site.committed, site.pr_open, site.building, site.verified, site.built, site.merged, site.production_wait, site.live, site.needs_attention, site.failed and site.waiting. The server may also send batch-level events; treat unknown event names as informational.

Entries in report:

  • live[]: siteId, site, repo, siteUrl, projectId, editorUrl.

  • attention[]: siteId, site, repo, siteUrl, reason, action (label, url, optional secondary, or null) and problems[] (code, message, optional fix with label and url).

  • failed[]: siteId, site, repo, siteUrl, reason.

  • pending[]: siteId, site, state, words (what the site is doing, in a sentence) and next (the one next step).

blockers[] must be fixed (exit 20); warnings[] change nothing (exit 0). The accounts Ulika searched are named in message. For a Next.js site with no Vercel account:

json
{"event":"preflight","site":"https://example.com","repository":"acme/site","ready":false,"blockers":[{"code":"vercel-not-connected","message":"example.com needs Vercel. No Vercel account is connected.","fix":{"label":"Connect Vercel","url":"https://ulika.co/dashboard/connect?url=https%3A%2F%2Fexample.com"}}],"warnings":[]}

A Vite site in the same state is "ready":true with the same entry under warnings[] and blockers empty.

A fuller walkthrough with examples is in Connect with the CLI.

Where the CLI keeps things#

PathHolds
~/.ulika/config.jsonYour authorisation, one record per Ulika address: workspace tokens under servers, agent tokens and any unanswered approval under agents. The folder is created readable only by you (mode 0700) and the file likewise (0600).
~/.ulika/batches.jsonThe id of each batch that is still running, so re-running the same command picks it up.
ulika.config.json (in your repository)The connection record: project id, name, site address, import time, number of fields and where content is served from. It holds no secret.

The local path also keeps a clone cache in ~/.ulika/repositories and installation state in ~/.ulika/installations. See Connect with the CLI for details.

Update notice#

When init runs on a local checkout and --json is not set, the CLI asks the Ulika server for /cli/version.json (waiting at most 1.5 seconds). If a newer version is available it prints the exact command for it. Any failure is silent.

Was this page helpful?

PreviousSecurity and privacy overviewNext CLI changelog

On this page

  • Running the CLI
  • Commands
  • connect
  • init
  • preview
  • login, logout, whoami
  • scan and status
  • codex
  • mcp
  • link
  • Options
  • Combinations the CLI rejects
  • Environment variables
  • Exit codes
  • JSON output
  • One object
  • One line per event
  • Where the CLI keeps things
  • Update notice
Ulika documentationFAQ · CLI reference · Terms · Privacy