here.now

Skill version: 1.8.3

Create a live URL from any file or folder. Static hosting only.

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

my-site/

my-site/index.html

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

.herenow/state.json

--claim-token {token}

Authenticated updates require a saved API key.

Client attribution

Pass

--client

./scripts/publish.sh {file-or-dir} --client cursor

This sends

X-HereNow-Client: cursor/publish-sh

API key storage

The publish script reads the API key from these sources (first match wins):

1. --api-key {key}

   flag (CI/scripting only — avoid in interactive use)

2. $HERENOW_API_KEY

   environment variable

3. ~/.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

Never commit credentials or local state files (

~/.herenow/credentials

.herenow/state.json

State file

After every site create/update, the script writes to

.herenow/state.json

{
  "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

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

Getting an API key

To upgrade from anonymous (24h) to permanent sites:

1. Ask the user for their email address.
2. Request a one-time sign-in code:

curl -sS https://here.now/api/auth/agent/request-code \
  -H "content-type: application/json" \
  -d '{"email": "user@example.com"}'

3. Tell the user: "Check your inbox for a sign-in code from here.now and paste it here."
4. 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":"user@example.com","code":"ABCD-2345"}'

5. 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

--slug {slug}

--claim-token {token}

--title {text}

--description {text}

--ttl {seconds}

--client {name}

cursor

--base-url {url}

https://here.now

--allow-nonherenow-base-url

--base-url

--api-key {key}

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"}}'

Beyond the script

For delete, metadata patch (including password protection), duplicate, claim, list, and other operations, see references/REFERENCE.md.

Handle

Handles are user-owned subdomain namespaces on

here.now

yourname.here.now

• Handle endpoints:

  /api/v1/handle

• Handle format: lowercase letters/numbers/hyphens, 2-30 chars, no leading/trailing hyphens

Custom domains

Bring your own domain (e.g.

example.com

• Domain endpoints:

  /api/v1/domains

  and

  /api/v1/domains/:domain

Add a custom domain

curl -sS https://here.now/api/v1/domains \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

The response includes

is_apex

ownership_verification

DNS setup by domain type:

• Subdomains (e.g.

  docs.example.com

  ): Add a CNAME record pointing to

  fallback.here.now

  .
• Apex domains (e.g.

  example.com

  ):
  1. Add an ALIAS record pointing to

     fallback.here.now

     . (Your DNS provider may call this ANAME or CNAME flattening.)
  2. Add a TXT record using the

     name

     and

     value

     from the

     ownership_verification

     field in the response.

SSL is provisioned automatically once DNS is verified.

Check domain status

curl -sS https://here.now/api/v1/domains/example.com \
  -H "Authorization: Bearer {API_KEY}"

Status is

pending

active

ownership_verification

verification_errors

List custom domains

curl -sS https://here.now/api/v1/domains \
  -H "Authorization: Bearer {API_KEY}"

Remove a custom domain

curl -sS -X DELETE https://here.now/api/v1/domains/example.com \
  -H "Authorization: Bearer {API_KEY}"

Removes the domain and all links under it.

Links

Links connect a site to a location on your handle or a custom domain. The same endpoints work for both — omit the

domain

• Link endpoints:

  /api/v1/links

  and

  /api/v1/links/:location

• Root location sentinel for path params:

  __root__

• Changes propagate globally in up to 60 seconds (Cloudflare KV)

Link to your handle:

curl -sS https://here.now/api/v1/links \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"location": "docs", "slug": "bright-canvas-a7k2"}'

Link to a custom domain:

curl -sS https://here.now/api/v1/links \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"location": "", "slug": "bright-canvas-a7k2", "domain": "example.com"}'

An empty

location

https://example.com/

"location": "docs"

https://example.com/docs/

Full docs: https://here.now/docs