Permaweb Deploy

permaweb-deploy uploads static sites, folders, or individual files to Arweave and can optionally update a Permaweb Name ~reference@1.0 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.

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 /~bundler@1.0/item?codec-device=ans104@1.0; 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

Name		Name	Last commit message	Last commit date
Latest commit History 242 Commits
.changeset		.changeset
.github		.github
.husky		.husky
.vscode		.vscode
bin		bin
docs		docs
src		src
tests		tests
.editorconfig		.editorconfig
.eslintignore		.eslintignore
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.nvmrc		.nvmrc
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
action.yml		action.yml
commitlint.config.js		commitlint.config.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json
vite.config.ts		vite.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

Permaweb Deploy

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

About

Uh oh!

Releases 8

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Permaweb Deploy

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

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 8

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages