Connect a site
Connect with the CLI
Connect one site or many from a terminal with one command and one browser approval. Covers connect, init, login, scan, status, link, JSON output and exit codes.
Last updated
The Ulika command line connects a website to Ulika from any computer. You run one command and approve once in your browser. If you use GitHub, that is the whole job: one command, one page. Ulika finds the repository, reads the site, opens a small connector change and, by default, puts it live for you. Nothing is cloned. npx downloads the CLI and runs it once, and nothing is installed permanently on your computer. The only thing installed anywhere is Ulika's GitHub App, on GitHub, and only if it is not there yet.
If you would rather click than type, use the dashboard. If you want an AI coding agent to do this for you, see Connect with an AI agent. Every option is listed in the CLI reference.
Before you start#
Node.js 20 or newer on the computer you run it from. That is the only local requirement for
connect.A GitHub account that can reach the repository that builds your site. You do not need a Ulika account first: Continue with GitHub creates it. You can also use email, see Approving once.
Ulika's GitHub App on that account or organisation. If it is not installed, the approval page sends you to install it once and brings you back.
A role that is allowed to create projects. An account you just created is an owner. Other roles see "cannot authorise a machine" and are told to ask an owner. See Roles.
Connect one site#
Run this from any folder, with your own site's address:
npx -y https://ulika.co/cli/ulika-cli-0.7.1.tgz connect https://your-site.comIf you installed the CLI globally (npm i -g https://ulika.co/cli.tgz), it is just:
ulika connect https://your-site.comWhat happens, in order:
First run on this computer: approval. The CLI prints one link and a short code, and opens your browser when it can. You confirm the code matches and click Approve this agent. This is the only approval you need. See Approving once.
Ulika does the work on its servers. It finds the repository that builds the address, reads your site, opens a pull request with the connector, waits for your host to build it, checks the live site and merges. You can close the window; the work continues on Ulika, and re-running the same command picks it up again.
A report. The command ends with a line such as
1 live · 0 need your attention · 0 failed, followed by the editor link of each live site.
While it runs, a terminal shows one line per change for each site. These are the plain-language steps:
| You see | Meaning |
|---|---|
| queued | The site is waiting its turn. |
| found its repository | Ulika tied the address to one repository. |
| reading the site | Ulika is reading the repository's content. |
| content imported | The editable content was imported. |
| changes prepared | The connector files are planned. |
| changes saved on a branch | The connector is committed to its own branch. |
| pull request opened | The connector pull request exists on GitHub. |
| waiting for the preview to build | Your host is building the connector preview. |
| preview checked | Ulika verified the preview. |
| preview built | The host reported a successful build (used when previews are private). |
| changes merged | The connector is merged into your default branch. |
| waiting for the live site to update | Ulika is waiting to see the connector on your real domain. |
| live | Done. The editor link follows. |
| live (already connected) | The site was already connected; nothing was changed. |
| needs you: ... | One person-only step is needed. The reason follows. |
| failed: ... | This site could not be connected. The reason follows. |
| paused, continuing at ... | Ulika hit a rate limit and will continue by itself. |
Which repository?#
Ulika only goes on when it is certain. It ties your address to one repository when the repository itself says which site it serves, when the Vercel project that lists your domain is linked to that repository (Ulika reads the project's domain list, which also covers a domain that redirects or has not been deployed to yet), or when your host (Vercel, Netlify, Cloudflare Pages, Render, Railway or AWS Amplify) reports exactly one production deployment on that address. On a *.vercel.app or *.netlify.app address the project name is the address's first label (and, for a Vercel preview address, the part before -git- or the build hash), and a project is normally named after its repository, so a repository with that name is offered as a candidate: you confirm it on the approval page or with the --repo command Ulika prints. A homepage field or a similar name on any other address is never enough on its own, and anything that looks like a backup, archive, fork or copy is never picked by itself. If it cannot be sure, the site ends as ambiguous-repository and you choose. You can also say which one:
ulika connect https://your-site.com --repo acme/website--repo takes exactly one owner/name and goes with exactly one address.
Check first, change nothing#
To see everything that would stop a site from connecting, all at once and without writing anything:
ulika connect https://your-site.com --checkIt still needs this computer to be approved, because it asks Ulika. It prints either <site> is ready to connect (owner/name) or <site> needs N fixes before Ulika can connect it, with a plain message and one fix link for each problem, then lists warnings. The exit code is 0 when ready and 20 when something blocks it. With --json it prints a single preflight line, with blockers and warnings apart. When you do not say how the site is delivered, Ulika reads the root package.json of the repository it resolves (the one you gave with --repo, or the one it finds from the site address): a Next.js site needs Vercel, so a missing or wrong Vercel account is a blocker, while a Vite or React build only gets a warning. This is a guess from the repository root; in a monorepo whose root does not depend on next it assumes nothing, and the real connect decides. If GitHub fails the read (a revoked or reduced installation, a rate limit, an outage), the check says so with a delivery-unknown warning instead of guessing. A package.json that is absent, too large or not a regular file infers nothing and prints nothing. The kinds of problems it can report are explained in CLI errors and exit codes.
Approving once#
The first command on a computer prints something like this (the numbers and address differ):
Approve once to connect your sites: https://ulika.co/connect?code=ABCD-EFGH (code ABCD-EFGH, expires in 15 minutes)The CLI opens the page automatically on a normal desktop session. It does not on CI, over SSH, with --no-browser, with --no-wait, or when ULIKA_NO_BROWSER=1; then you open the link yourself. Without a terminal (a script, an agent), the command does not wait for the approval: it prints the link to standard error and exits with code 22. With --wait it waits instead, and a line such as Still waiting for approval… 14 min left repeats every minute, so it is never silent.
Just before a new link, the CLI prints Checking <site>… and shows what Ulika can already see of each of the first two distinct sites you passed: whether it is reachable, how many pages its sitemap lists with a few example paths, and where it is hosted. This preview is anonymous and optional. If Ulika has checked too many sites from your network in the last 10 minutes, the CLI prints when to try again and carries on to the approval; an older server, a network error or an answer slower than 10 seconds simply skips it. It is not shown again when a pending code is reused or this computer is already approved. With --json it is a site_preview event.
On the approval page, signed out:
Click Continue with GitHub. The first time, this creates your Ulika account and a workspace named after your site (for example
acme.com). You can rename it in your workspace settings. Sign in with email and Create an account with email are the second path; with email you name the workspace yourself after you confirm your address.If GitHub shares no verified email, the same page says Add your email to continue and asks for one. You confirm it from the email Ulika sends, and no second account is created.
If Ulika's GitHub App is not installed on your account, GitHub offers to install it. Do it once and you come back to this page. If an organisation owner has to approve the install, the page tells you; open the link again once they have.
Your code survives sign-in, sign-up, GitHub and email confirmation. If you open the confirmation email in a different browser, you still land on the approval page, as long as you are on the same network, the code is still open and you have not used this shortcut for it before. Otherwise open the link your terminal printed. Running the command again reuses the same code and opens the browser again, unless one of the opt-outs above applies.
Then, signed in:
Check that the code matches the one in your terminal. The page also shows the agent, when and from where it was requested, your workspace and your connected GitHub accounts. Only approve if you just started this from your own terminal.
Read what approving means: Ulika adds its connector to each repository it connects (a small folder and one build setting) in a pull request. By default Ulika opens a pull request and merges nothing until you activate it. 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. If your host keeps previews private, Ulika merges (on its own, or when you activate) once the host reports a successful build, and checks your live site right after.
Leave Merge automatically once the build passes unticked for the default (one Activate link per site), or tick it to let Ulika merge by itself. Running the command with
--auto-mergepre-ticks it.--review-firstis the default and does nothing.Click Approve this agent. The page tells you to return to your terminal. Deny refuses.
Ulika checks your GitHub accounts live when you open the page, so an install you made days ago still counts. If GitHub does not answer, the page says so and offers Try again; nothing is approved until it can read your accounts.
When Ulika cannot tell which repository serves your site, the report says ambiguous-repository, which just means "Ulika will not guess". The approval page then lists the likely repositories from your GitHub accounts, or shows the one it found for you to click to confirm. Ulika never asks you to type a repository name.
| What you choose | What happens | What to run |
|---|---|---|
| A repository from the list | The CLI uses it for this run only, exactly as if you had passed --repo owner/name. An explicit --repo always wins over it. | Nothing more. |
| None of these | The command never asks again. The site ends in the attention list as ambiguous-repository, with the exact command to run. | ulika connect <url> --repo owner/name. |
| A repository in another organisation or account | Ulika cannot reach it until its GitHub App is installed there. | Install the App there, then the same command with --reapprove. |
The command then continues by itself and prints Approved. The code lives about 15 minutes, and the CLI waits for at most that long. After that the command exits with code 22 and says Nobody approved the request in time. Run it again for a new link.
What an approval allows#
The approval creates an agent token. It can connect sites from the repositories your GitHub account has shared with Ulika, and read batch progress; it cannot publish content, read drafts, invite people or manage tokens. It stops working after 30 days, or after 14 days without being used. It is limited to 50 sites in any rolling 24 hours (see The 24-hour site cap). You can see and revoke approved agents under Agents in your workspace settings.
For scripts and CI#
Use --no-wait so the command never blocks:
ulika connect https://your-site.com --json --no-wait # prints the link, exits 22
# a person approves the link
ulika connect https://your-site.com --json # collects the approval and runsThe first run keeps its request on disk, so the second run collects that same approval instead of printing a new link. You can also give a stored agent token through the ULIKA_TOKEN environment variable (it must start with ovl_at_), which skips the approval.
Review before it goes live#
By default Ulika opens the pull request and waits for you to activate it. With automatic merge it merges the connector itself once your host has built it and the live site shows the connector, and undoes its own merge if the production build fails. A site stops for a person when it needs one: you did not choose automatic merge, branch protection wants a human review or a check Ulika cannot satisfy, or Ulika cannot see your host's builds.
When that happens the CLI prints one Ulika link and one sentence, for example:
• acme.com
Open this link and click Activate to put Ulika on your live site.
https://ulika.co/dashboard/connect?connection=...
Prefer GitHub? Review and merge PR #16: https://github.com/acme/website/pull/16The sentence is fixed. The last line (shown dimmed in a terminal) is only a secondary option, because a browser that is not signed in to GitHub shows a 404 for a private pull request. The CLI then keeps waiting, with a status line every 30 seconds (Still waiting for you to click Activate… N min left), and finishes when the site is live. It stops waiting after 15 minutes, or the number of minutes you pass with --wait-timeout (1 to 120), and exits with code 20. Activate from the link any time afterwards and run the same command to pick the site up. With --no-wait it does not wait at all, and neither does a run without a terminal (a script, an agent, CI): it prints the state and the link, then exits with code 20 while you still have to act, or while Ulika is still verifying a merged site (nothing is needed from you; run the same command again later). --no-browser only stops the browser from opening. Pass --wait to keep waiting without a terminal; it cannot be combined with --no-wait.
Connect many sites#
One approval connects any number of sites. The work runs on Ulika's servers, so the laptop can sleep and the terminal can close.
ulika connect --all # every site in the repositories Ulika can see
ulika connect --urls sites.txt # one address per line, or a comma-separated list
ulika connect --repos acme/web,acme/blog # repositories instead of addresses
ulika connect https://acme.com https://blog.acme.com
ulika connect --resume bat_123 # follow a batch that is already running--urls and --repos take a comma- or space-separated list, or a file path. In a file, anything after # on a line is ignored. Addresses are normalised (Acme.com/ becomes https://acme.com). A positional owner/name counts as a repository; anything else as an address.
How a batch works:
Ulika runs it, you follow it. The CLI submits the batch, then reads Ulika's event log. Re-running the same command while its batch is still running re-attaches to it instead of starting another; so does
--resume <batchId>. The batch id is thebatchIdfield of thebatchevent in the JSON stream, and the CLI repeats it in the hint it prints if its connection to Ulika drops.Each site is independent. A site that needs a person is set aside with one next action, never guessed at, and the others carry on. Ulika works on at most three sites at a time per workspace.
Nothing is connected twice. A site or repository your workspace already has attaches to its existing row: live sites are reported again as
live (already connected); sites that needed you are queued again.Busy servers are handled. On a busy answer the CLI backs off (starting at one second, up to a minute, honouring
Retry-After) for up to eight tries and printsUlika is busy, trying again in Nsfor waits of five seconds or more.Limits. One batch holds at most 50 sites, and an agent token may take on at most 50 in any rolling 24 hours.
--all shows you the list first#
--all is a list nobody typed, so nothing is written until a person has seen it. In a terminal the CLI prints Ulika found N sites: with each site and repository, then asks Connect these N sites? [y/N]. Without a terminal, or with --json, it prints the list and exits with code 23, having written nothing; run the same command again with --yes once the person agreed. --urls and --repos are lists you typed, so they start at once.
ulika connect --all --json --no-wait # 1. exit 22: relay the approval link
ulika connect --all --json # 2. exit 23: prints confirmation_required with the list
ulika connect --all --json --yes # 3. only after the person agreed: connects and reports
ulika connect --resume bat_123 --json # 4. if the process died, pick the same batch back upThe report#
When every site is settled the CLI prints a headline and one line per site:
2 live · 1 needs your attention · 0 failed
✓ acme.com https://ulika.co/...
✓ blog.acme.com https://ulika.co/...
• shop.acme.com the pull request is waiting for you to merge it
Open this link and click Activate to put Ulika on your live site.
https://ulika.co/dashboard/connect?connection=...(The check and bullet characters become OK and * on a plain Windows console.) A site appears under one of four headings:
Live: with its editor link.
Needs your attention: with the reason in plain words and one next action. Run the same command again after you have done it. The reasons are explained in Connect attention reasons and, for the CLI's own wording, in CLI errors and exit codes.
Failed: with the reason.
Still in progress: a count.
The exit code summarises it: 0 when at least one site is live and none failed, 21 when any failed, 20 when none went live and none failed.
--json output#
--json turns off the spinner, colour and prompts. How it looks depends on the command.
A batch or one address through the GitHub App#
connect prints one JSON object per line (newline-delimited JSON), as things happen. Every line has event. The last line is report on success or error on failure.
{"event":"site_preview","status":"ok","site":"https://acme.com","finalUrl":"https://acme.com/","reachable":true,"pages":{"count":7,"sample":["/","/about"],"truncated":false},"framework":{"value":"nextjs","confidence":"high"},"hosting":{"value":"vercel","confidence":"certain"}}
{"event":"browser_plan","steps":["Continue with GitHub, or sign in with email, to identify yourself.","Install Ulika's GitHub App on the account that owns the repository, if asked.","Click Approve."],"expiresInMinutes":15}
{"event":"approval_required","url":"https://ulika.co/connect?code=ABCD-EFGH","code":"ABCD-EFGH","expiresAt":"2026-10-10T12:15:00.000Z","browserOpened":true,"expiresInMinutes":15}
{"event":"approved"}
{"event":"batch","batchId":"bat_123","resumed":false,"sites":1}
{"event":"site.pr_open","id":"41","at":"2026-10-10T12:01:00.000Z","siteId":"s1","site":"acme.com"}
{"event":"site.live","id":"57","at":"2026-10-10T12:05:00.000Z","siteId":"s1","site":"acme.com","projectId":"prj_1","editorUrl":"https://ulika.co/..."}
{"event":"report","batchId":"bat_123","summary":{"live":1,"needsAttention":0,"failed":0,"pending":0},"live":[{"siteId":"s1","site":"acme.com","repo":"acme/website","siteUrl":"https://acme.com","projectId":"prj_1","editorUrl":"https://ulika.co/..."}],"attention":[],"failed":[],"pending":[],"exitCode":0}(The values are illustrative; the field names are the real ones.) Find each event by its event name rather than by line number: site_preview (once per site, only before a new code) and browser_plan come before approval_required when the code is new or the browser is opening, and is left out when a reused code is polled again. Read the exit code, then the last line. For every item in report.attention[], show its reason and its one action.label and action.url. If a site waits for Activate, the stream also contains an activation_required line, then waiting lines every 30 seconds, and possibly activation_timeout. The full list of events and fields is in the CLI reference.
A site Ulika folds into another one (the same repository asked for twice, once by address and once by --all) still gets its own site.queued line; afterwards only the surviving site reports.
On failure the last line is:
{"event":"error","code":"unauthorized","error":"...","hint":"...","exitCode":11}code is one of usage, unauthorized, forbidden, not_found, bad_request, conflict, site_cap, network, server_error, or an approval code: approval_required, denied, expired, bad_response.
One object#
init, scan, status, link, login, logout, whoami, version and a local one-site connect print one pretty-printed JSON object and exit. Their fields are in the CLI reference.
Connect from a checkout: init#
If you are already inside the website's checkout, ulika init reads it directly, with no site address needed, and the scan never leaves your computer: only the derived content manifest is sent (paths, sample values, file names and line numbers), not your source code.
ulika init # in the checkout
ulika init --dry-run # scan and print, send nothing
ulika init https://your-site.com --repo owner/nameinit derives everything it needs: the project name (from package.json, humanised), the framework, the repository and branch (from the Git remote), and the site address (from ulika.config.json, then vercel.json alias, then netlify.toml, then the homepage in package.json, then the production domain of the Vercel project linked to the repository, and only then the GitHub Pages address, as a last resort). A missing address is never a blocker: it is sent empty and set later in the app. Re-running init in a connected repository refreshes the project instead of creating a duplicate. Fields the scan is at least 85 percent sure about are approved on arrival; the rest are flagged for review after the site is already connected.
The local path needs your own tools: Git, the Vercel CLI and the GitHub CLI, signed in. It prepares a reviewable connector pull request and verifies the preview. Merging and verifying production is a separate, deliberate step:
ulika init https://your-site.com --activateOther options used with a checkout:
--localmakes an address resolve through this computer's checkout,vercelandghinstead of the GitHub App.--dir <path>points at a project folder other than the current one.--scope <team>names the Vercel team.--import-onlyimports content without installing the connector.--confirm-domainagrees that your address belongs to a repository that advertises another domain. Without it, a script exits with code 25 and a terminal asks first.
When init ends, it prints what happened step by step: requested domain, repository identified, project configured, domain connected (yes with production verified, or not yet), the connector pull request, and the next action. Exit code 0 means everything is done, 15 means the connector pull request still needs review or activation, and 16 means installing the connector did not finish after the import. See CLI errors and exit codes.
The other commands#
ulika login, logout, whoami#
ulika login authorises this computer for your workspace, once. It prints a code (for example W X Y Z - 1 2 3 4), opens your browser, and you click Approve on a page that says what the machine will be able to do: create projects in your workspace and import content from repositories you run it in. It cannot read your source code, only the manifest the scan produces. The result is stored locally and every later init in any repository is zero-click. ulika whoami shows who this computer is authorised as, and ulika logout forgets it.
login is mainly for the checkout path. connect has its own approval (an agent token) and does not need login.
ulika scan#
Prints exactly what Ulika would learn about a checkout: framework, repository, routes, how many text, image, link and SEO fields it found, and a sample of 20 with their file and line. It never touches the network. It reads at most 2000 files and 1000 fields and skips folders such as node_modules, .git, .next, dist, build, out, coverage and any hidden folder.
ulika status#
Reads ulika.config.json and reports the project, the site, the number of fields, when it was imported and the installation state (active or imported, with the last verification time).
ulika link#
ulika link <token> joins a project that already exists in Ulika using a single-use pairing token that starts with ovl_live_. It prints what will be sent and asks Send it and link this project? (--yes skips the question). init and connect are the documented paths and need no token.
The 24-hour site cap#
Each approved agent can take on at most 50 sites in any rolling 24 hours, across all its batches. Re-running the same list is not new work. Past the limit, Ulika answers with a site_cap error and the CLI exits with code 24 without retrying. Wait until earlier sites age out of the 24 hours, or approve a new agent.
Weekly re-approval for organisations#
Ulika cannot see someone leave a GitHub organisation, so for repositories that belong to an organisation, an approval is only good for writing for seven days. After that the site is set aside with the reason reapproval-required, and the CLI prints:
Run the same command with --reapprove to approve this machine again; it picks up where it stopped.--reapprove drops this computer's stored agent token and asks a person to approve again. Repositories owned by a personal GitHub account, and reading progress, are not affected.
Where credentials are stored#
Everything the CLI remembers is under ~/.ulika in your home folder; the folder is readable only by you.
| File | Holds |
|---|---|
~/.ulika/config.json | Your authorisation, one record per Ulika address: a workspace token (ovl_wt_...) from login, and, separately, the agent token (ovl_at_...) from connect, plus any approval that is still unanswered. The file is written readable only by you (mode 600). |
~/.ulika/batches.json | The id of each batch that is still running, so re-running the same command re-attaches to it. |
The two tokens live next to each other and never replace each other: an agent token can connect sites but cannot publish, so it never overwrites a human's workspace token. A machine that was authorised against Ulika's previous address keeps working with https://ulika.co. The local checkout path also keeps clones in ~/.ulika/repositories and installation state in ~/.ulika/installations.
ULIKA_TOKEN in the environment wins over anything stored. The connection record ulika.config.json inside your repository holds no secret.
Update check#
When ulika init runs on a checkout and --json is not set, the CLI asks Ulika for /cli/version.json and waits at most 1.5 seconds. If a newer CLI exists it prints:
A newer Ulika CLI (X.Y.Z) is available. Run:
npx -y https://ulika.co/cli/ulika-cli-X.Y.Z.tgz initAny failure is silent and never delays the command further. Using the versioned address matters because npx caches a tarball by its address and would otherwise keep running the first copy it fetched.
Exit codes at a glance#
| Code | Meaning |
|---|---|
| 0 | At least one site is live and none failed. |
| 20 | No site is live and none failed: every site needs a person. This includes the four Vercel reasons. |
| 21 | At least one site failed. A site waiting for Vercel is never a 21. |
| 22 | Approval is still required. |
| 23 | The --all list was not confirmed. Nothing was written. |
| 24 | The 24-hour site cap is spent. |
| 25 | Local connect: the repository advertises another domain; confirm it. |
The complete table, with causes and fixes, is in CLI errors and exit codes and in the CLI reference.
Was this page helpful?