here.now
Skill version: 1.11.0
Create a live URL from any file or folder. Static hosting with optional proxy routes for calling external APIs server-side.
To install or update (recommended): npx skills add heredotnow/skill --skill here-now -g
For repo-pinned/project-local installs, run the same command without -g.
Requirements
- Required binaries:
curl, file, jq
- Optional environment variable:
$HERENOW_API_KEY
- Optional credentials file:
~/.herenow/credentials
Create a site
./scripts/publish.sh {file-or-dir}
Outputs the live URL (e.g. https://bright-canvas-a7k2.here.now/).
Under the hood this is a three-step flow: create/update -> upload files -> finalize. A site is not live until finalize succeeds.
Without an API key this creates an anonymous site that expires in 24 hours.
With a saved API key, the site is permanent.
File structure: For HTML sites, place index.html at the root of the directory you publish, not inside a subdirectory. The directory's contents become the site root. For example, publish my-site/ where my-site/index.html exists — don't publish a parent folder that contains my-site/.
You can also publish raw files without any HTML. Single files get a rich auto-viewer (images, PDF, video, audio). Multiple files get an auto-generated directory listing with folder navigation and an image gallery.
Update an existing site
./scripts/publish.sh {file-or-dir} --slug {slug}
The script auto-loads the claimToken from .herenow/state.json when updating anonymous sites. Pass --claim-token {token} to override.
Authenticated updates require a saved API key.
Client attribution
Pass --client so here.now can track reliability by agent:
./scripts/publish.sh {file-or-dir} --client cursor
This sends X-HereNow-Client: cursor/publish-sh on publish API calls.
If omitted, the script sends a fallback value.
API key storage
The publish script reads the API key from these sources (first match wins):
--api-key {key} flag (CI/scripting only — avoid in interactive use)$HERENOW_API_KEY environment variable~/.herenow/credentials file (recommended for agents)
To store a key, write it to the credentials file:
mkdir -p ~/.herenow && echo "{API_KEY}" > ~/.herenow/credentials && chmod 600 ~/.herenow/credentials
IMPORTANT: After receiving an API key, save it immediately — run the command above yourself. Do not ask the user to run it manually. Avoid passing the key via CLI flags (e.g. --api-key) in interactive sessions; the credentials file is the preferred storage method.
Never commit credentials or local state files (~/.herenow/credentials, .herenow/state.json) to source control.
State file
After every site create/update, the script writes to .herenow/state.json in the working directory:
{
"publishes": {
"bright-canvas-a7k2": {
"siteUrl": "https://bright-canvas-a7k2.here.now/",
"claimToken": "abc123",
"claimUrl": "https://here.now/claim?slug=bright-canvas-a7k2&token=abc123",
"expiresAt": "2026-02-18T01:00:00.000Z"
}
}
}
Before creating or updating sites, you may check this file to find prior slugs.
Treat .herenow/state.json as internal cache only.
Never present this local file path as a URL, and never use it as source of truth for auth mode, expiry, or claim URL.
What to tell the user
- Always share the
siteUrl from the current script run.
- Read and follow
publish_result.* lines from script stderr to determine auth mode.
- When
publish_result.auth_mode=authenticated: tell the user the site is permanent and saved to their account. No claim URL is needed.
- When
publish_result.auth_mode=anonymous: tell the user the site expires in 24 hours. Share the claim URL (if publish_result.claim_url is non-empty and starts with https://) so they can keep it permanently. Warn that claim tokens are only returned once and cannot be recovered.
- Never tell the user to inspect
.herenow/state.json for claim URLs or auth status.
Limits
|
Anonymous |
Authenticated |
| Max file size |
250 MB |
5 GB |
| Expiry |
24 hours |
Permanent (or custom TTL) |
| Rate limit |
5 / hour / IP |
60 / hour free, 200 / hour hobby |
| Account needed |
No |
Yes (get key at here.now) |
Getting an API key
To upgrade from anonymous (24h) to permanent sites:
- Ask the user for their email address.
- Request a one-time sign-in code:
curl -sS https://here.now/api/auth/agent/request-code \
-H "content-type: application/json" \
-d '{"email": "[email protected]"}'
- Tell the user: "Check your inbox for a sign-in code from here.now and paste it here."
- Verify the code and get the API key:
curl -sS https://here.now/api/auth/agent/verify-code \
-H "content-type: application/json" \
-d '{"email":"[email protected]","code":"ABCD-2345"}'
- Save the returned
apiKey yourself (do not ask the user to do this):
mkdir -p ~/.herenow && echo "{API_KEY}" > ~/.herenow/credentials && chmod 600 ~/.herenow/credentials
Script options
| Flag |
Description |
--slug {slug} |
Update an existing site instead of creating |
--claim-token {token} |
Override claim token for anonymous updates |
--title {text} |
Viewer title (non-HTML sites) |
--description {text} |
Viewer description |
--ttl {seconds} |
Set expiry (authenticated only) |
--client {name} |
Agent name for attribution (e.g. cursor) |
--base-url {url} |
API base URL (default: https://here.now) |
--allow-nonherenow-base-url |
Allow sending auth to non-default --base-url |
--api-key {key} |
API key override (prefer credentials file) |
--spa |
Enable SPA routing (serve index.html for unknown paths) |
--forkable |
Allow others to fork this site |
SPA routing
For React, Vue, Svelte, and other single-page applications, pass --spa when publishing:
./scripts/publish.sh ./dist --spa
This tells here.now to serve index.html for any path that doesn't match a real file, so client-side routing works on refresh and direct links. Without --spa, unknown paths return 404.
You can also toggle SPA mode on an existing site without re-publishing:
curl -sS -X PATCH https://here.now/api/v1/publish/{slug}/metadata \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-d '{"spaMode": true}'
Asset paths: Make sure the build uses root-relative paths (/assets/app.js) not bare relative paths (assets/app.js). Vite and Create React App do this by default.
Duplicate a site
curl -sS -X POST https://here.now/api/v1/publish/{slug}/duplicate \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-d '{}'
Creates a full copy of the site under a new slug. All files are copied server-side — no upload needed. The new site is immediately live. Requires authentication and ownership of the source site.
Optionally override viewer metadata (shallow-merged with the source):
curl -sS -X POST https://here.now/api/v1/publish/{slug}/duplicate \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-d '{"viewer": {"title": "My Copy"}}'
Forking a site
Publishers can allow others to fork their sites. When a site has forkable: true, its file manifest is exposed and visitors see a fork button.
Publishing a forkable site:
./scripts/publish.sh ./dist --forkable
Or toggle on an existing site:
curl -sS -X PATCH https://here.now/api/v1/publish/{slug}/metadata \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-d '{"forkable": true}'
Forking an existing forkable site:
- Fetch the file manifest:
GET https://{slug}.here.now/.herenow/manifest.json
- Download each file from:
GET https://{slug}.here.now/.herenow/raw/{path}
- Publish the files with
--forkable to keep the fork chain going
The manifest returns a JSON object with files (array of {path, size}), spaMode, and requiredVariables (variables needed for proxy routes, with upstream domains).
If the site has proxy routes, the .herenow/proxy.json file is included in the download. The forker needs to set up their own variables for the proxy routes to work. Check requiredVariables in the manifest for what's needed.
Forkable is mutually exclusive with password protection and payment gating — disable one before enabling the other.
Beyond the script
For delete, metadata patch (including password protection and payment gating), duplicate, claim, list, and other operations, see references/REFERENCE.md.
Payment gating
Sites can require stablecoin payment on the Tempo network before granting access. Payments go directly from the visitor's wallet to the publisher's wallet.
To receive payments you need a Tempo wallet address. Get one at wallet.tempo.xyz or by running npx mppx account create.
CLI commands:
herenow wallet set 0xYOUR_ADDRESS --api-key $HERENOW_API_KEY
herenow price set <slug> 0.50 --api-key $HERENOW_API_KEY
herenow price set <slug> 1.00 --wallet 0xOTHER_ADDRESS --api-key $HERENOW_API_KEY
herenow price remove <slug> --api-key $HERENOW_API_KEY
herenow wallet --api-key $HERENOW_API_KEY
Payment gating and password protection are mutually exclusive. You can also manage payments from the dashboard (Wallet tab for address, site menu for pricing).
Accessing a paid site
If you fetch a here.now URL and get a 402 Payment Required response, the site requires payment.
If you have Tempo wallet + mppx installed: payment is handled automatically. No action needed.
If you have the Tempo CLI: run tempo request <url> to pay and retrieve the content.
If you don't have Tempo: use the payment session flow. The 402 response body includes paymentSession URLs:
{
"price": { "amount": "0.10", "currency": "USD" },
"paymentSession": {
"createUrl": "https://here.now/api/pay/<slug>/session",
"pollUrl": "https://here.now/api/pay/<slug>/poll",
"grantUrl": "https://here.now/api/pay/<slug>/grant"
},
"walletUrl": "https://wallet.tempo.xyz/"
}
Steps:
POST <createUrl> to get a unique deposit address and session ID- Show the user the amount, deposit address, and wallet link (
https://wallet.tempo.xyz/)
- Poll
POST <pollUrl> with {"sessionId": "<id>"} every 3 seconds
- When the response has
"found": true, call POST <grantUrl> with {"sessionId": "<id>", "txHash": "<hash>"}
- The response contains a
token. Fetch the original URL with ?__hn_grant=<token> to get the content.
Example message to the user:
This site requires payment of $0.10 (USD) on the Tempo network.
Send $0.10 to: 0xBd46...DbB6
If you need a Tempo wallet: https://wallet.tempo.xyz/
The agent should poll silently and present the content once payment is detected.
Service variables and proxy routes
Sites can make authenticated API calls to external services without exposing secrets in client
