Valet|Docs
Sign up

CLI: Artifacts

An artifact is a directory of static files served over HTTPS at a generated hostname. Create an artifact, then run valet deploy from the linked directory to publish its content. The URL is live (serving 404s) as soon as the artifact is created. Artifacts are the fastest way to put a report, a dashboard, a prototype, or a folder of files on a URL you control.

Prefer working from a coding agent? The valet-publish skill wraps this entire flow — see Common Workflows.

The CLI still spells the command valet sites. Every command, flag, and line of output below is exactly what the CLI prints today.

Create an artifact

valet sites create [name] [--org <org>]

The artifact gets a generated hostname (like bright-prism-1937) under the platform's own domain. The current directory is linked to the new artifact so valet deploy publishes it. The artifact name is optional — if omitted, the server generates one. Artifact, app, and agent names share one namespace within an org.

$ valet sites create my-site
Creating site... done, my-site
Linking directory... done
URL: https://bright-prism-1937.valet.run
Run "valet deploy" to publish this directory.

New artifacts are private by default — only members of the owning org can view them, after a Valet login.

Deploy

valet deploy

Run from the linked directory. Everything in the directory is uploaded except .git/, .valet/, the root valet.yaml, and symlinks. An index.html at the root is served as the artifact; without one, visitors get a browsable file listing. If the local source is identical to what has already deployed, deploy exits without re-releasing.

Describe the artifact with valet.yaml

An artifact's name is a DNS-safe hostname, which tells a reader nothing. Write a valet.yaml beside index.html to label the artifact in the dashboard and in valet sites output. The file itself is never uploaded.

name: q3-migration-audit
display_name: Q3 Migration Audit
description: Findings and rollback plan from the Q3 datastore migration.

Control who can view it

valet sites access <name> [public|private|password] [--password <value>]

With no mode, prints the artifact's current access mode. With a mode, moves the artifact to it:

  • private — Members of the owning org, after a Valet login. New artifacts are private by default.
  • password — Org members sign in with Valet, or any visitor enters the artifact password. The password is for external users; sessions last 24 hours.
  • public — Anyone on the internet.

Password mode prompts for a hidden password; pass --password in scripts or agent runs where stdin is not a terminal. Switching away from password mode clears the stored password. Any change signs every current visitor out.

$ valet sites access my-site public
Setting my-site access to public in acme org... done
Anyone can now view this site.

Anonymous artifacts — publish with no account

valet sites create --anonymous

Creates an artifact with no Valet account at all. It lands in a shared incubator org, it is public to anyone with the link, it takes a generated name, and it may be removed 36 hours after it is created unless it is claimed. Its claim token — the only credential that can update, delete, or claim it — is written into .valet/config.json in the current directory, which should not be committed.

$ valet sites create --anonymous
Creating anonymous site... done, bubbling-brook-1934
URL: https://bubbling-brook-1934.try.valet.run
Expires in 3h 54m (2026-07-31 03:14 UTC)
Claim URL: https://valet.dev/claim/RZ2m7q...
Linking directory... done
Run "valet deploy" to publish this directory.

--anonymous takes no artifact name and cannot be combined with --org. It is refused when you are signed in: valet sites create <name> followed by valet sites access <name> public makes a permanent public artifact in your own org instead. It also refuses to replace an existing link; pass --relink to mean it.

Claim an anonymous artifact

valet sites claim [name] --org <org> [--name <new-name>]

Claiming transfers an anonymous artifact into an org you belong to, gives it a permanent URL, and leaves the anonymous URL redirecting there. The claim consumes the artifact's claim token: afterwards the artifact is managed through org membership like any other. A claimed artifact stays public — everyone holding the shared link keeps access. Run valet sites access <name> private to change that.

--org is required and must name an org you already belong to — the command never creates one. For a brand-new org, run valet orgs create <org> first, or use the browser claim URL printed at creation, which does both at once. Use --name to rename the artifact on the way in. An anonymous artifact can only be claimed from the directory it was published from; from anywhere else, use the claim URL.

Update an artifact from anywhere

valet sites download <name> [dir] [--force]

Downloads the artifact's currently-deployed files into a local directory and links that directory to the artifact. This is how one agent or person updates an artifact another created: a static artifact has no build step, so its deployed release is the source of truth — the downloaded copy is exactly what the artifact serves, ready to edit and redeploy. The directory must be empty unless --force is given.

$ valet sites download docs-site
Downloading docs-site... done, 12 files to docs-site/
Linking directory... done
Run "valet deploy" from docs-site to publish changes.

Link a directory

valet sites link <name> [--org <org>] [--force]

Creates a .valet/config.json that maps this directory to the named artifact so valet deploy publishes to it. Use link only when you already have the artifact's files — linking an empty directory and deploying replaces the artifact with an empty release. To recover a lost directory, use valet sites download instead.

List artifacts and artifact info

valet sites [--org <org>]
valet sites info [name]

valet sites lists artifacts in the default organization with name, URL, and version. valet sites info shows the artifact's org, URL, current release with its deploy age, access mode, and any attached drains. In a directory linked to an anonymous artifact, valet sites info with no name reports that artifact's standing — its expiry while live, or where it went once claimed.

$ valet sites info docs-site
=== Site: docs-site (acme org)
  org:        acme-corp
  url:        https://apt-lens-2877.valet.run
  release:    v3 (deployed 2h12m ago)
  access:     private (org members only, via Valet login)
  drains:     https://in.logs.example.com/x (active)

Destroy an artifact

valet sites destroy [name]

Permanently destroys the artifact and all its releases. The hostname stops serving within seconds and is never reused. Cannot be undone. Run with no name in a directory linked to an anonymous artifact to take that artifact down with its claim token — no account needed.