Media-heavy site: update without re-uploading photos
A heavy site is published file by file, not as an archive:
npx @tuqo/cli deploy ./dist --site <id> first asks the server which files it does not have
yet and uploads only those. So the first deploy of a 300-photo catalog takes a while, and
the second one, after you changed a single price in the text, takes seconds: not one photo is
uploaded again. Unlike an archive upload, there is no request body size limit at all.
Why an archive does not work
An archive goes up whole, even if one line changed. And the ceilings are hard:
| Publishing path | Ceiling |
|---|---|
| A folder dropped into the panel | up to 2000 files, about 36 MB |
A tar.gz or zip archive in the panel | 50 MB |
deploy_site over MCP or REST | 50 MB (base64 archive) |
The CLI (@tuqo/cli) | up to 2000 files, up to 50 MB per file, in total within your plan’s storage |
A photographer’s site with 400 shots almost never fits into 50 MB. And even when it does, every text edit pushes tens of megabytes again.
How it works
The CLI is a thin wrapper around the public manifest deploy REST API, in three steps:
POST /api/v1/sites/{id}/deploys/check: send the{path, sha256}list of all site files; the server answers which blobs it does not have yet.PUT /api/v1/blobs/{sha256}: upload only the missing files, one by one, as raw bytes.POST /api/v1/sites/{id}/deploys/manifest: publish the manifest; the stored blobs are copied into the site’s files on the storage side.
Deduplication is by sha256 within the project: the same photo used in two sites, or in twenty deploys in a row, is stored and uploaded once. The bytes never pass through the platform’s memory: copying happens inside S3 storage.
Step 1. A project key
Panel → project → API keys → create. editor rights are enough to deploy.
The full key, tqk_<prefix>_<secret>, is shown once; after that you can only reissue it,
and the database keeps only a hash.
Pass the key in the TUQO_API_KEY environment variable (alias TUQO_KEY), not with the
--key flag: that way it stays out of your shell history and ps. It must not be in
tuqo.json either; the CLI refuses to run if it finds a key there.
Step 2. Deploy
TUQO_API_KEY=tqk_xxx_yyy npx @tuqo/cli deploy ./dist --site <site_id> --waitThere is nothing to install: npx downloads the package on first run; you need Node.js 18
or newer. --wait waits for publishing and prints the live URL, and in CI it exits with
code 1 if the deploy failed. Useful flags and recipes for GitHub Actions and GitLab CI are on
the CLI page and in the guide on
deploying from GitHub Actions and GitLab CI.
Want to show a version to a client before it goes live? Deploy with --no-activate, get a
secret link with the preview command and publish with promote. Until then the live address
shows the previous version. See build preview.
Step 3. Updates
Change the text, run the same command, and the CLI asks the server again what is missing.
The answer: “only index.html”. One file goes up, the photos stay where they are. A repeat
deploy with no changes is almost instant.
If an AI agent edits the site
An agent in a browser chat has no disk access and sends files through its own context. For a media site that is slow and expensive. Two ways around it:
get_manifest(site_id)returns the{path, sha256}list of the active version’s files. Indeploy_files, unchanged files are passed as a{path, sha256}reference with nocontent, so the bytes never pass through the model’s context at all. Only the files that actually change carry content; the set is still always complete, not a patch.- An agent with a terminal (Claude Code, Cursor) publishes a heavy site with the same
npx @tuqo/cli deploycommand: the bytes are read from disk and no tokens are spent on base64.
How much fits
The total size is limited by your plan’s storage: Free has 150 MB, Start 1 GB, Pro 3 GB, Business 7 GB, Scale 15 GB, Enterprise 45 GB. You can buy more storage in packs from 149 ₽/mo (+500 MB, +1 GB, +3 GB, +10 GB). Kept versions count toward storage, so on plans that keep several copies a gallery takes space in several deploys. You control that with the “Copies to keep” setting in the site settings. Numbers, add-ons and approximate prices in dollars and euros are on the pricing page.
FAQ
How is the CLI different from uploading an archive?
An archive goes up whole on every edit; the CLI sends only the changed files. There is also no request body size limit: files go one by one, up to 50 MB each.
Do I need to install anything?
No, npx @tuqo/cli downloads the package on first run. You need Node.js 18 or newer; the
package has no dependencies.
How do I make the site lighter?
Scale images down to their real on-screen size and do not embed them in the HTML as base64 strings: such a page has to load completely before the first paint, and base64 does not compress. The “Images embedded in HTML” check flags this after publishing; see all publish checks.
What if the site’s repository is on GitHub, GitVerse or GitFlic?
Then it is simpler without the CLI: connect Git CD, and Tuqo builds and publishes the site on every push. The CLI is for when the build runs in your own CI or on your machine. See auto-deploy from Git.