@ar.io/deploy

v1.0.0

Published

10 hours ago

ARIO Deploy — CLI for deploying apps to the permaweb (Arweave) and updating ArNS

0High
0Medium
0Low

ARIO Deploy

ario-deploy is a Node.js command-line tool designed to streamline the deployment of web applications to the permaweb using Arweave. It uploads your build folder or a single file, creates Arweave manifests, and can optionally update ArNS (Ar.io Name System) records via ANT (Ar.io Name Token) with the transaction ID.

Quick Start

Deploy your app to Arweave in under a minute:

# Install
npm install -g @ar.io/deploy

# Deploy (interactive — prompts for everything)
ario-deploy deploy

# Or one-liner with a Solana wallet + ArNS name
DEPLOY_KEY=<solana-base58-key> ario-deploy deploy --deploy-folder ./dist --arns-name myapp --sig-type solana

Your app is now permanently live at https://myapp.ar.io.

Features

Turbo SDK Integration: Uses Turbo SDK for fast, reliable file uploads to Arweave
On-Demand Payment: Pay with ARIO or Base-ETH tokens on-demand during upload
Arweave Manifest v0.2.0: Creates manifests with fallback support for SPAs
Optional ArNS Updates: Updates ArNS records via ANT with new transaction IDs
Automated Workflow: Integrates with GitHub Actions for continuous deployment
Git Hash Tagging: In CI (GitHub Actions), tags uploaded data items with the deploying commit SHA
404 Fallback Detection: Automatically detects and sets 404.html as fallback
Network Support: ArNS updates run against the Solana ARIO programs on mainnet or devnet, with an optional custom RPC URL
Flexible Deployment: Supports deploying a folder or a single file
Modern CLI: Built with oclif for a robust command-line experience
TypeScript: Fully typed for better developer experience

Installation

Install the package using pnpm (recommended):

pnpm add -D @ar.io/deploy

Or with npm:

npm install --save-dev @ar.io/deploy

Or with yarn:

yarn add --dev @ar.io/deploy

Prerequisites

A deployment uses up to two independent keys:

Upload key — pays for the upload. Any supported chain (--wallet / --private-key, or the DEPLOY_KEY env var; chain selected with --sig-type).
ArNS authority key — only needed when updating ArNS. Always a Solana key that controls the ArNS name and signs the ANT record update (--arns-wallet / --arns-private-key, or the ARNS_KEY env var).

They can be the same Solana wallet or two different wallets — provide each explicitly.

Upload key (`DEPLOY_KEY`)

Arweave signer (default): Encode your Arweave wallet key in base64 and set it as DEPLOY_KEY:
```
base64 -i wallet.json | pbcopy
```
Ethereum/Polygon/KYVE signers: Use your raw private key (no encoding needed) as DEPLOY_KEY.
Solana signer: Use a base58-encoded secret key as DEPLOY_KEY, or a solana-keygen id.json byte-array wallet file via --wallet.

ArNS authority key (`ARNS_KEY`)

Set a base58-encoded Solana secret key as ARNS_KEY, or pass a solana-keygen id.json file via --arns-wallet (or a base58 string via --arns-private-key). This key must control the ArNS name being updated.

⚠️ Important: Use dedicated wallets for deployments to minimize security risks. Ensure your upload wallet has sufficient Turbo Credits for uploads.

Commands

Interactive Mode (Easiest)

Run the deploy command without arguments to be guided through all deployment options:

ario-deploy deploy

When ArNS details aren't supplied via flags, deploy asks whether you want to update an ArNS name (defaulting to yes) and, if so, prompts for the details. It will guide you through:

Whether to update an ArNS name (and which one)
Wallet method (file, string, or environment variable)
What to deploy (folder or file)
Advanced options (optional: undername, TTL, Solana cluster)

Pass --arns-name (or --use-arns) to skip the ArNS confirmation, or use the upload command for an upload-only run. In a non-interactive environment (CI, or no TTY) deploy does not prompt — supply everything via flags or DEPLOY_KEY.

Direct Commands

Use flags for faster, scriptable deployments:

# Basic deployment with wallet file
ario-deploy deploy --wallet ./wallet.json

# Deployment with ArNS update (separate upload key + Solana ArNS authority key)
ario-deploy deploy --use-arns --arns-name my-app --wallet ./wallet.json --arns-wallet ./arns-id.json

Deploy using private key directly:

ario-deploy deploy --private-key "$(cat wallet.json)"

Deploy using environment variable:

DEPLOY_KEY=$(base64 -i wallet.json) ario-deploy deploy --deploy-folder ./dist

Deploy a specific folder:

ario-deploy deploy --wallet ./wallet.json --deploy-folder ./build

Deploy a single file:

ario-deploy deploy --wallet ./wallet.json --deploy-file ./path/to/file.txt

Upload/deploy without ArNS

deploy uploads without updating ArNS by default. You can also use the upload command explicitly for the same Turbo upload, dedupe cache, and payment options as deploy, minus ArNS flags:

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

Advanced Usage

Deploy to an undername (subdomain) — the ArNS authority key is a Solana wallet:

ario-deploy deploy --use-arns --arns-name my-app --wallet ./wallet.json --arns-wallet ./arns-id.json --undername staging

Deploy with a custom TTL:

ario-deploy deploy --use-arns --arns-name my-app --wallet ./wallet.json --arns-wallet ./arns-id.json --ttl-seconds 7200

Update ArNS on devnet (or against a custom RPC):

ario-deploy deploy --use-arns --arns-name my-app --wallet ./wallet.json --arns-wallet ./arns-id.json --cluster devnet
ario-deploy deploy --use-arns --arns-name my-app --wallet ./wallet.json --arns-wallet ./arns-id.json --rpc-url https://my-rpc.example.com

Upload using an Ethereum wallet (file):

ario-deploy deploy --sig-type ethereum --wallet ./private-key.txt

Upload using a Solana wallet (base58 private key):

ario-deploy deploy --sig-type solana --private-key "<base58-secret-key>"

On-Demand Payment

Use on-demand payment to automatically fund uploads with ARIO or Base-ETH tokens when your Turbo balance is insufficient:

Deploy with ARIO on-demand payment:

ario-deploy deploy --wallet ./wallet.json --deploy-folder ./dist --on-demand ario --max-token-amount 1.5

Deploy with Base-ETH on-demand payment (using Ethereum signer):

ario-deploy deploy --sig-type ethereum --private-key "0x..." --on-demand base-eth --max-token-amount 0.1

On-Demand Payment Options:

--on-demand: Token to use for on-demand payment (ario or base-eth)
--max-token-amount: Maximum token amount to spend (in native token units, e.g., 1.5 for 1.5 ARIO or 0.1 for 0.1 ETH)

How it works:

Checks your Turbo balance before upload
If balance is insufficient, converts tokens to Turbo credits on-demand
Automatically adds a 10% buffer (topUpBufferMultiplier: 1.1) for reliability
Proceeds with upload once funded

Token compatibility:

ARIO: Works with Arweave signer
Base-ETH: Works with Ethereum signer (Base Network)

Bundler service

Uploads go through a bundler service that accepts signed data items and posts them to Arweave. By default, ario-deploy uses the Turbo API and ArDrive’s production bundler (https://upload.ardrive.io). --uploader sets the base URL of the bundler service to use (scheme + host; typically no path).

| When to use | Example value | | ------------------------- | ------------------------------------------------------- | | Default (omit flag) | ArDrive production bundler — same as Turbo CLI defaults | | Arweave bundler | https://turbo.ardrive.io | | Development / staging | https://upload.ardrive.dev | | Custom or self-hosted | Your own base URL if it implements the Turbo API |

Examples:

# Deploy using Arweave’s bundler service
ario-deploy deploy --wallet ./wallet.json --deploy-folder ./dist --uploader https://turbo.ardrive.io

ario-deploy upload --wallet ./wallet.json --deploy-folder ./dist --uploader https://turbo.ardrive.io

Notes:

Turbo billing and signer behavior follow Turbo.
Use a base URL only (e.g. https://turbo.ardrive.io), not a path to a specific file or route.

Command Options

deploy (upload by default, optional ArNS update):

--use-arns: Update an ArNS/ANT record after upload. When ArNS details aren't supplied and you're in a TTY, deploy asks by default.
--arns-name, -n: The ArNS name to update. Required when using --use-arns; also implies ArNS mode.
--cluster, -p: Solana cluster for ArNS updates. Choices: mainnet, devnet. Default: mainnet
--rpc-url: Optional Solana RPC URL override for ArNS updates
--deploy-folder, -d: Folder to deploy. Default: ./dist
--deploy-file, -f: Deploy a single file instead of a folder
--undername, -u: ANT undername to update. Default: @
--ttl-seconds, -t: TTL in seconds for the ANT record (60-86400). Default: 60

Upload key (pays for the upload):

--sig-type, -s: Signer type for the upload key. Choices: arweave, ethereum, polygon, kyve, solana. Default: arweave
--wallet, -w: Path to the upload wallet file (JWK for Arweave, private key for Ethereum/Polygon/KYVE, solana-keygen id.json for Solana). Falls back to DEPLOY_KEY.
--private-key, -k: Upload private-key string (alternative to --wallet). JWK JSON for Arweave, hex for EVM chains, base58 secret key for Solana.

ArNS authority key (controls the name, signs the update — always Solana):

--arns-wallet: Path to the Solana solana-keygen id.json wallet that controls the ArNS name. Falls back to ARNS_KEY.
--arns-private-key: Base58 Solana secret key for the ArNS authority (alternative to --arns-wallet). Falls back to ARNS_KEY.
--on-demand: Enable on-demand payment with specified token. Choices: ario, base-eth
--max-token-amount: Maximum token amount for on-demand payment (used with --on-demand)
--no-dedupe: Disable deduplication (do not cache or reuse previous uploads)
--dedupe-cache-max-entries: Maximum number of entries to keep in the dedupe cache (LRU). Default: 10000
--uploader: Custom Turbo upload service base URL. See the Bundler service section.

upload (explicit upload without ArNS): accepts --deploy-folder, --deploy-file, wallet/signer flags, --uploader, --on-demand / --max-token-amount, and dedupe flags only.

Deduplication

By default, ario-deploy caches your deployment log to prevent uploading duplicate (unchanged) files. This saves both time and upload costs by reusing existing data on Arweave.

How it works:

When you deploy, ario-deploy hashes each file in your build
It checks the local cache for matching hashes from previous uploads
Files that haven't changed are skipped - the existing transaction ID is reused
Only new or modified files are uploaded to Arweave
The cache is stored locally in .ario-deploy/transaction-cache.json

Disable deduplication:

If you need to force a fresh upload of all files (e.g., for debugging or to ensure a completely new deployment):

ario-deploy deploy --wallet ./wallet.json --no-dedupe

Limit cache size:

The dedupe cache uses an LRU (Least Recently Used) eviction strategy. By default, it keeps up to 10,000 entries. You can adjust this limit:

# Keep only the last 1000 file entries
ario-deploy deploy --wallet ./wallet.json --dedupe-cache-max-entries 1000

Cache location:

The cache file is stored at .ario-deploy/transaction-cache.json in your project root. You can:

Add it to .gitignore if you don't want to share cache across team members
Commit it to share cached transaction IDs with your team (reduces duplicate uploads)
Delete it to start fresh: rm -rf .ario-deploy/

Package.json Scripts

Add deployment scripts to your package.json:

{
  "scripts": {
    "build": "vite build",
    "deploy": "pnpm build && ario-deploy deploy --arns-name <ARNS_NAME>",
    "deploy:staging": "pnpm build && ario-deploy deploy --arns-name <ARNS_NAME> --undername staging",
    "deploy:devnet": "pnpm build && ario-deploy deploy --arns-name <ARNS_NAME> --cluster devnet",
    "deploy:on-demand": "pnpm build && ario-deploy deploy --arns-name <ARNS_NAME> --on-demand ario --max-token-amount 1.5"
  }
}

These read the upload key from DEPLOY_KEY and the Solana ArNS authority key from ARNS_KEY. Deploy with:

DEPLOY_KEY=$(base64 -i wallet.json) ARNS_KEY=<base58-solana-secret-key> pnpm deploy

Or with on-demand payment:

DEPLOY_KEY=$(base64 -i wallet.json) ARNS_KEY=<base58-solana-secret-key> pnpm deploy:on-demand

GitHub Action

The easiest way to integrate ario-deploy into your CI/CD pipeline is using our official GitHub Action.

Basic Usage

- uses: ar-io/ar-io-deploy@v1
  with:
    deploy-key: ${{ secrets.DEPLOY_KEY }} # upload key (pays for the upload)
    arns-key: ${{ secrets.ARNS_KEY }} # Solana ArNS authority key
    arns-name: myapp
    deploy-folder: ./dist

PR Preview Deployments

Automatically deploy preview builds for each pull request. The preview mode auto-generates an undername from the PR number and posts a comment with the preview URL:

name: Deploy PR Preview

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  deploy-preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build

      - name: Deploy Preview
        uses: ar-io/ar-io-deploy@v1
        with:
          deploy-key: ${{ secrets.DEPLOY_KEY }}
          arns-key: ${{ secrets.ARNS_KEY }}
          arns-name: myapp
          preview: 'true'
          github-token: ${{ secrets.GITHUB_TOKEN }}
          deploy-folder: ./dist

When preview is enabled, the action will:

Auto-generate an undername like pr-123 from the PR number
Post a comment on the PR with the preview URL
Update the comment on subsequent pushes instead of creating new ones

Production Deployment

Deploy to your base ArNS name when pushing to main:

name: Deploy to Production

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build

      - name: Deploy to Permaweb
        uses: ar-io/ar-io-deploy@v1
        with:
          deploy-key: ${{ secrets.DEPLOY_KEY }}
          arns-key: ${{ secrets.ARNS_KEY }}
          arns-name: myapp
          deploy-folder: ./dist

With On-Demand Payment

- name: Deploy with ARIO on-demand
  uses: ar-io/ar-io-deploy@v1
  with:
    deploy-key: ${{ secrets.DEPLOY_KEY }}
    arns-key: ${{ secrets.ARNS_KEY }}
    arns-name: myapp
    deploy-folder: ./dist
    on-demand: ario
    max-token-amount: '2.0'

Updating ArNS (Solana)

ArNS updates run against the Solana ARIO programs. Provide the Solana ArNS authority key via arns-key (a base58 Solana secret key); the upload is still paid for by deploy-key. Use cluster to target mainnet (default) or devnet, and rpc-url for a custom RPC endpoint.

- name: Deploy and update ArNS
  uses: ar-io/ar-io-deploy@v1
  with:
    deploy-key: ${{ secrets.DEPLOY_KEY }} # upload key
    arns-key: ${{ secrets.ARNS_KEY }} # Solana ArNS authority key
    arns-name: myapp
    deploy-folder: ./dist
    cluster: mainnet

Disabling Deduplication

By default, the action caches transaction IDs to avoid re-uploading unchanged files. To disable this:

- name: Deploy without dedupe
  uses: ar-io/ar-io-deploy@v1
  with:
    deploy-key: ${{ secrets.DEPLOY_KEY }}
    deploy-folder: ./dist
    no-dedupe: 'true'

You can also limit the cache size:

- name: Deploy with limited cache
  uses: ar-io/ar-io-deploy@v1
  with:
    deploy-key: ${{ secrets.DEPLOY_KEY }}
    deploy-folder: ./dist
    dedupe-cache-max-entries: '1000'

CLI in GitHub Actions

You can also use the CLI directly in your workflows:

Basic Workflow:

name: Deploy to Permaweb

on:
  push:
    branches:
      - main

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v3
        with:
          version: 9

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'

      - run: pnpm install

      - run: pnpm deploy
        env:
          DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}

With On-Demand Payment:

name: Deploy to Permaweb with On-Demand Payment

on:
  push:
    branches:
      - main

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v3
        with:
          version: 9

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'

      - run: pnpm install
      - run: pnpm build

      - name: Deploy with ARIO on-demand
        run: ario-deploy deploy --arns-name my-app --on-demand ario --max-token-amount 2.0
        env:
          DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }} # upload key (pays for the upload)
          ARNS_KEY: ${{ secrets.ARNS_KEY }} # Solana ArNS authority key


      # Or upload with Ethereum and Base-ETH on-demand payment (upload only; ArNS requires Solana):
      # - name: Upload with Base-ETH on-demand
      #   run: |
      #     ario-deploy upload \
      #       --sig-type ethereum \
      #       --on-demand base-eth \
      #       --max-token-amount 0.2
      #   env:
      #     DEPLOY_KEY: ${{ secrets.ETH_PRIVATE_KEY }}

Claude Code Integration

Use Claude Code to deploy your app with natural language. Just say "deploy to ar.io" and Claude handles the rest.

Add the Skill to Your Project

mkdir -p .claude/skills
curl -o .claude/skills/deploy.md https://raw.githubusercontent.com/ar-io/ar-io-deploy/main/examples/claude-skill/deploy.md

Then in Claude Code, say:

"deploy to ar.io"
"deploy my app to arweave"
"set up CI/CD for ar.io deployment"

Claude will build your project, detect the output folder, and run the deploy with the right flags.

What the Skill Does

Detects your build folder (./dist, ./build, ./out)
Checks for credentials (DEPLOY_KEY env var or wallet file)
Installs @ar.io/deploy if not already available
Runs the deployment with appropriate flags
Reports results — transaction ID, Arweave URL, ArNS URL

See examples/claude-skill/ for the full skill file and customization options.

Development

Setup

# Install dependencies
pnpm install

# Build the project
pnpm build

# Run in development mode
pnpm dev

# Run tests
pnpm test

# Run linter
pnpm lint

# Format code
pnpm format

Project Structure

ar-io-deploy/
├── src/
│   ├── commands/        # oclif commands
│   │   ├── deploy.ts
│   │   └── upload.ts
│   ├── types/           # TypeScript type definitions
│   │   └── index.ts
│   ├── utils/           # Utility functions
│   │   ├── constants.ts
│   │   ├── signer.ts
│   │   ├── uploader.ts
│   │   └── __tests__/   # Unit tests
│   └── index.ts         # Main entry point
├── bin/                 # Executable scripts
│   ├── run.js
│   └── dev.js
├── .changeset/          # Changesets configuration
├── .husky/              # Git hooks
└── dist/                # Build output

Security & Best Practices

Dedicated Wallet: Always use a dedicated wallet for deployments to minimize security risks
Wallet Encoding: Arweave wallets must be base64 encoded to be used in the deployment script
ArNS Name: Required only when updating an ANT/ArNS target undername or root record
Turbo Credits: Ensure your wallet has sufficient Turbo Credits, or use on-demand payment for automatic funding
On-Demand Limits: Set reasonable --max-token-amount limits to prevent unexpected costs
Secret Management: Keep your DEPLOY_KEY secret secure and never commit it to your repository
Build Security: Always check your build for exposed environmental secrets before deployment, as data on Arweave is permanent

Troubleshooting

Error: "DEPLOY_KEY environment variable not set": Verify your base64 encoded wallet is set as the DEPLOY_KEY environment variable
Error: "deploy-folder does not exist": Check that your build folder exists and the path is correct
Error: "deploy-file does not exist": Check that your build file exists and the path is correct
Error: "ArNS name does not exist": Verify the ArNS name is correct and exists in the specified network
Upload timeouts: Files have a timeout for upload. Large files may fail and require optimization
Insufficient Turbo Credits: Use --on-demand with --max-token-amount to automatically fund uploads when balance is low
On-demand payment fails: Ensure your wallet has sufficient tokens (ARIO or Base-ETH) and the token type matches your signer (ario with Arweave, base-eth with Ethereum)

Contributing

Contributions are welcome! Please follow these guidelines:

Fork the repository
Create a feature branch
Make your changes
Run tests and linter: pnpm test && pnpm lint
Create a changeset: pnpm changeset
Commit your changes using conventional commits
Push and create a pull request

Conventional Commits

This project uses Conventional Commits. Commit messages should follow this format:

type(scope): subject

body (optional)

Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert

Changesets

We use changesets for version management. When making changes:

pnpm changeset

Follow the prompts to describe your changes.

Dependencies

@ar.io/sdk - For ANT operations and ArNS management on Solana
@ardrive/turbo-sdk - For fast file uploads to Arweave (and signer types)
@solana/kit - Solana RPC clients and transaction signers for ArNS updates
bs58 - Base58 encoding/decoding for Solana keys
@oclif/core - CLI framework
mime-types - MIME type detection