Permaweb Deploy

permaweb-deploy uploads static sites, folders, or individual files to Arweave and can optionally update a Permaweb Name [email protected] ref value with the deployed transaction or manifest ID.

Package rename: The npm package has moved from permaweb-deploy to @permaweb/deploy. The CLI command remains permaweb-deploy.

The CLI uses legacy ANS-104 bundlers for the default upload path, supports HyperBEAM bundlers when selected explicitly, and publishes names updates through @permaweb/references.

Table of Contents

• Features
• Quick Start
• Installation Options
• Prerequisites
• CLI Usage
• Names Publishing
• Bundlers
• Command Options
• Deduplication
• Package Scripts
• GitHub Action
• Development
• Troubleshooting
• Dependencies
• License

Features

• Arweave uploads: Upload a folder or a single file.
• Names publishing: Update a Permaweb Names reference-id's value after upload.
• Legacy bundler uploads: Use legacy ANS-104 upload endpoints by default.
• HyperBEAM uploads: Sign ANS-104 items and post them to a HyperBEAM bundler route.
• Arweave manifests: Create manifest 0.2.0 documents for folder deployments, with SPA fallback detection.
• Dedupe cache: Reuse unchanged uploads from .permaweb-deploy/transaction-cache.json.
• GitHub Action: Deploy from CI and optionally update a namespace reference.

Quick Start

Install the CLI in your project:

pnpm add -D @permaweb/deploy

Make your Arweave JWK available with either DEPLOY_KEY or --wallet:

export DEPLOY_KEY=$(base64 -i wallet.json)

If you prefer not to export a key, pass --wallet ./wallet.json to the commands below.

Upload a built static folder:

permaweb-deploy upload --deploy-folder ./dist

Deploy and update a Permaweb Name:

permaweb-deploy deploy --use-names --name my-app --deploy-folder ./dist

Or deploy and update a direct reference ID:

permaweb-deploy deploy --use-names --reference-id REFERENCE_ID --deploy-folder ./dist

For repeatable project scripts, add a build-and-deploy command:

{
  "scripts": {
    "build": "vite build",
    "deploy": "pnpm build && permaweb-deploy deploy --use-names --name my-app"
  }
}

Installation Options

pnpm add -D @permaweb/deploy

npm install --save-dev @permaweb/deploy

yarn add --dev @permaweb/deploy

Prerequisites

For the default Arweave signer, store your Arweave JWK as base64:

base64 -i wallet.json

Set the encoded value as DEPLOY_KEY, or pass --wallet ./wallet.json.

Names updates currently require --sig-type arweave, because reference updates are signed as ANS-104 data items and posted to the names bundler endpoint. Ethereum, Polygon, and KYVE signers remain supported for upload-only flows.

Use a dedicated deployment wallet and make sure it has enough upload credits/balance for the selected legacy bundler.

CLI Usage

Upload only:

permaweb-deploy deploy --wallet ./wallet.json --deploy-folder ./dist
permaweb-deploy upload --wallet ./wallet.json --deploy-file ./dist/index.html
DEPLOY_KEY=$(base64 -i wallet.json) permaweb-deploy upload --deploy-folder ./dist

Upload and update a reference-id pointed value using the namespace name:

permaweb-deploy deploy --use-names --name my-app --wallet ./wallet.json

Upload and update a direct reference ID:

permaweb-deploy deploy --use-names --reference-id REFERENCE_ID --wallet ./wallet.json

Advanced: use a custom namespace root reference or namespace manifest ID:

permaweb-deploy deploy \
  --use-names \
  --name my-app \
  --names-namespace NAMESPACE_ROOT_OR_MANIFEST_ID \
  --wallet ./wallet.json

Deploy a specific target:

permaweb-deploy deploy --use-names --name my-app --wallet ./wallet.json --deploy-folder ./build
permaweb-deploy deploy --use-names --name my-app --wallet ./wallet.json --deploy-file ./path/to/file.txt

Names Publishing

--name resolves the name inside the configured namespace manifest and updates that reference. --reference-id bypasses namespace lookup and updates the reference directly.

The default namespace is the phase-2 namespace exported by @permaweb/references. Override it with --names-namespace when you want to publish against another namespace root reference or manifest.

Useful flags:

• --use-names: update a Permaweb Names reference after upload.
• --name, -n: namespace name to update.
• --reference-id: reference ID to update directly.
• --names-namespace: namespace root reference or manifest ID used to resolve --name.
• --names-gateway: gateway for reference and namespace reads. Default: https://arweave.net.
• --names-graphql: GraphQL endpoint for reference discovery. Default: <names-gateway>/graphql.

Bundlers

By default, uploads use the legacy ANS-104 endpoint at https://up.arweave.net. Pass --uploader to choose a different base URL.

permaweb-deploy upload --wallet ./wallet.json --deploy-folder ./dist --uploader https://up.arweave.net

HyperBEAM upload:

permaweb-deploy upload \
  --wallet ./wallet.json \
  --deploy-folder ./dist \
  --uploader-type hyperbeam

When --uploader-type hyperbeam is set and --uploader is omitted, the CLI discovers active PermawebOS HyperBEAM uploaders and randomly selects a usable node. HyperBEAM uploads always check that the selected or pinned node wallet has more than 0 AR before posting data, because the node must be able to seed data to Arweave. Pass --uploader https://hyperbeam.example.com to pin a specific node and bypass discovery.

List discoverable HyperBEAM uploaders:

permaweb-deploy hyperbeam-uploaders
permaweb-deploy hyperbeam-uploaders --json

HyperBEAM auto-fund:

permaweb-deploy upload \
  --wallet ./wallet.json \
  --deploy-folder ./dist \
  --uploader-type hyperbeam \
  --hyperbeam-auto-fund

HyperBEAM uploads require an Arweave JWK signer. The default route is /[email protected]/[email protected]; override it with --hyperbeam-upload-path if your node exposes a different route.

Command Options

deploy supports upload flags plus names publishing flags:

• --deploy-folder, -d: folder to deploy. Default: ./dist.
• --deploy-file, -f: deploy a single file instead of a folder.
• --sig-type, -s: signer type. Choices: arweave, ethereum, polygon, kyve. Default: arweave.
• --wallet, -w: path to wallet file.
• --private-key, -k: private key or JWK JSON string.
• --no-dedupe: disable dedupe cache.
• --dedupe-cache-max-entries: LRU cache size. Default: 10000.
• --uploader: bundler service base URL. Legacy uploads default to https://up.arweave.net; HyperBEAM uploads auto-discover an active PermawebOS uploader when omitted.
• --uploader-type: upload protocol, legacy or hyperbeam. Default: legacy.
• --hyperbeam-upload-path: HyperBEAM bundler route.
• --hyperbeam-auto-fund: fund the HyperBEAM local ledger before upload.
• --hyperbeam-fund-amount: optional minimum HyperBEAM local ledger balance override.
• --hyperbeam-token-id: advanced AO token process ID override.
• --hyperbeam-ledger-id: advanced local HyperBEAM ledger ID override.
• --hyperbeam-ao-state-url: AO state endpoint used while waiting for auto-fund assignment.
• --use-names, --name, --reference-id, --names-namespace, --names-gateway, --names-graphql: names publishing options.

upload accepts upload, wallet, signer, bundler, and dedupe flags only.

Deduplication

The dedupe cache avoids re-uploading unchanged files. It hashes each deployed file and stores transaction IDs in .permaweb-deploy/transaction-cache.json.

Disable dedupe:

permaweb-deploy deploy --use-names --name my-app --wallet ./wallet.json --no-dedupe

Limit cache size:

permaweb-deploy deploy --use-names --name my-app --wallet ./wallet.json --dedupe-cache-max-entries 1000

Package Scripts

{
  "scripts": {
    "build": "vite build",
    "deploy": "pnpm build && permaweb-deploy deploy --use-names --name <NAME>",
    "deploy:ref": "pnpm build && permaweb-deploy deploy --use-names --reference-id <REFERENCE_ID>"
  }
}

DEPLOY_KEY=$(base64 -i wallet.json) pnpm deploy

GitHub Action

- uses: permaweb/permaweb-deploy@v1
  with:
    deploy-key: ${{ secrets.DEPLOY_KEY }}
    name: myapp
    deploy-folder: ./dist

Use a direct reference ID:

- uses: permaweb/permaweb-deploy@v1
  with:
    deploy-key: ${{ secrets.DEPLOY_KEY }}
    reference-id: ${{ secrets.NAMES_REFERENCE_ID }}
    deploy-folder: ./dist

PR preview names:

name: Deploy PR Preview

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  deploy-preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run build
      - uses: permaweb/permaweb-deploy@v1
        with:
          deploy-key: ${{ secrets.DEPLOY_KEY }}
          preview: 'true'
          github-token: ${{ secrets.GITHUB_TOKEN }}
          deploy-folder: ./dist

When preview is enabled, the action generates a namespace name from the repository and PR number, deploys the content, updates that name, and posts or updates a PR comment.

Action inputs for names publishing:

• name: namespace name to update.
• reference-id: reference ID to update directly.
• names-namespace: namespace root reference or manifest ID.
• names-gateway: gateway for reference and namespace reads.
• names-graphql: GraphQL endpoint for reference discovery.
• auto-name: generate a namespace name from PR number or branch name.
• preview: enable auto-name and post a PR comment.

Development

pnpm install
pnpm build
pnpm test
pnpm lint

Project layout:

permaweb-deploy/
├── src/commands
├── src/constants
├── src/prompts
├── src/types
├── src/utils
├── src/workflows
├── tests
└── bin

Troubleshooting

• DEPLOY_KEY environment variable not set: pass --wallet, pass --private-key, or set DEPLOY_KEY.
• Names updates currently require --sig-type arweave: reference updates are signed as ANS-104 data items; use an Arweave JWK for names updates.
• Name [...] does not exist in namespace ...: verify the namespace manifest contains the name or use --reference-id.
• signer is not reference authority: use the wallet that controls the target reference.
• deploy-folder does not exist: check the build output path.
• deploy-file does not exist: check the file path.
• Legacy upload rejected: check the upload endpoint response and retry with another legacy bundler if needed.

Dependencies

• @permaweb/references - namespace reference reads and writes.
• @dha-team/arbundles - ANS-104 data item signing.
• @permaweb/aoconnect - AO network connectivity.
• @permaweb/hyperbalance - HyperBEAM auto-fund support.
• @oclif/core - CLI framework.
• mime-types - MIME type detection.

License

ISC