### Installing and Starting aos Shell

Source: https://github.com/permaweb/ao/blob/main/lua-examples/ao-standard-token/README.md

Instructions to install the `aos` command-line tool globally using npm and then launch the `aos` interactive shell. This is the prerequisite for interacting with ao processes as demonstrated in subsequent snippets.

```sh
npm i -g https://get_ao.g8way.io && aos
```

--------------------------------

### Setup Local Development Tools Rust

Source: https://github.com/permaweb/ao/blob/main/servers/su/README.md

Installs the necessary Rust tools `systemfd` and `cargo-watch` for hot reloading during local development.

```Shell
cargo install systemfd cargo-watch
```

--------------------------------

### Start ao Unit Router (Production) - Shell

Source: https://github.com/permaweb/ao/blob/main/servers/ur/README.md

This command starts the `ao` Unit Router service using the standard npm start script. It's typically configured for production or normal runtime operation. Ensure dependencies are installed (`npm i`) and required environment variables are set.

```Shell
npm start
```

--------------------------------

### Sending 'hello' Message via REPL

Source: https://github.com/permaweb/ao/blob/main/lua-examples/hello-world/README.md

Demonstrates sending the 'hello' message to the 'hello-world' ao process using the local `repl.js` script. This message triggers an update to the process's internal state, setting `heardHello` to true and incrementing `helloCount`.

```Shell
hello world > hello
```

--------------------------------

### Requesting Raw State via REPL

Source: https://github.com/permaweb/ao/blob/main/lua-examples/hello-world/README.md

Demonstrates sending the 'raw' message to the 'hello-world' ao process using the local `repl.js` script. This message triggers a read action, returning the process's current internal state as a stringified JSON object.

```Shell
hello world > raw
```

--------------------------------

### Sending 'world' Message via REPL

Source: https://github.com/permaweb/ao/blob/main/lua-examples/hello-world/README.md

Demonstrates sending the 'world' message to the 'hello-world' ao process using the local `repl.js` script. This message triggers an update to the process's internal state, setting `heardWorld` to true.

```Shell
hello world > world
```

--------------------------------

### Spawning a New ao Process

Source: https://github.com/permaweb/ao/blob/main/connect/README.md

Provides an example of using the `spawn` function to create a new ao process. It requires specifying the module, scheduler, a signer, and optional tags and initial data for the process.

```JavaScript
import { createSigner, spawn } from "@permaweb/aoconnect";

const processId = await spawn({
  module,
  scheduler,
  signer: createSigner(wallet),
  tags,
  data,
});
```

--------------------------------

### Installing Latest ao CLI Version (sh)

Source: https://github.com/permaweb/ao/blob/main/dev-cli/README.md

Downloads and executes the latest `ao` CLI install script from the dedicated gateway URL `https://install_ao.g8way.io`. This is the recommended way to get the most recent CLI version. Requires `curl` and `bash`. Follow post-installation prompts to add `ao` to your PATH.

```sh
curl -L https://install_ao.g8way.io | bash
```

--------------------------------

### Sending 'ping' Message to a Friend Process

Source: https://github.com/permaweb/ao/blob/main/lua-examples/hello-world/README.md

Demonstrates sending a 'ping' message to another process (a 'friend') using the local `repl.js`, specifying the friend's process ID. If the friend is also a hello-world process, it is designed to send a 'pong' message back.

```Shell
hello world > ping <friend_id>
```

--------------------------------

### Installing ao CLI from Arweave TXID (sh)

Source: https://github.com/permaweb/ao/blob/main/dev-cli/README.md

Downloads and executes the `ao` CLI install script for a specific version published on Arweave, identified by its transaction ID. Requires `curl` and `bash`. The `{txId}` should be replaced with the actual transaction ID found in the project's `deno.json` file.

```sh
curl -L https://arweave.net/{txId} | bash
```

--------------------------------

### Start ao Unit Router (Development) - Shell

Source: https://github.com/permaweb/ao/blob/main/servers/ur/README.md

This command starts the `ao` Unit Router service in a development mode, often enabling features like hot-reloading for faster iteration. It's recommended for local development work. Requires dependencies installed (`npm i`).

```Shell
npm run dev
```

--------------------------------

### Sending 'friend' Message to Spawn Process

Source: https://github.com/permaweb/ao/blob/main/lua-examples/hello-world/README.md

Demonstrates sending the 'friend' message to the 'hello-world' ao process via the local `repl.js`. This message includes a source ID (`src-id`) and triggers a write action that results in spawning a new process using the specified source code (in this case, the hello-world source itself).

```Shell
hello world > friend V4Z_o704ILkjFX6Dy93ycoKerywfip94j07dRjxMCPs
```

--------------------------------

### Initializing Default Lua Project (sh)

Source: https://github.com/permaweb/ao/blob/main/dev-cli/README.md

Creates and initializes a new directory named `myproject` (or the current directory if omitted) with the default `ao` project structure, specifically setting up a Lua SmartWeaveContract template. Requires the `ao` CLI to be installed and in your PATH.

```sh
ao init [myproject]
```

--------------------------------

### Install Dependencies for ao Unit Router - Shell

Source: https://github.com/permaweb/ao/blob/main/servers/ur/README.md

This command installs all required Node.js packages and dependencies for the ao Unit Router project, as specified in the `package.json` file. This step is necessary before running or developing the service.

```Shell
npm i
```

--------------------------------

### Displaying Main ao CLI Help (sh)

Source: https://github.com/permaweb/ao/blob/main/dev-cli/README.md

Shows the general help documentation for the `ao` command-line interface, listing available commands and global options. Use this to get an overview of the CLI's capabilities and usage. Requires the `ao` CLI.

```sh
ao --help
```

--------------------------------

### Sending 'pong' Message to a Friend Process

Source: https://github.com/permaweb/ao/blob/main/lua-examples/hello-world/README.md

Demonstrates sending a 'pong' message to another process (a 'friend') using the local `repl.js`, specifying the friend's process ID. If the friend is also a hello-world process, it will simply accept the 'pong' message without sending a response.

```Shell
hello world > pong <friend_id>
```

--------------------------------

### Running ao Compute Unit with npm

Source: https://github.com/permaweb/ao/blob/main/servers/cu/README.md

These shell commands are used to manage the ao Compute Unit project dependencies and execution. `npm i` installs all required packages, `npm start` runs the application in production mode, and `npm run dev` starts it with development features like hot-reloading.

```Shell
npm i
```

```Shell
npm start
```

```Shell
npm run dev
```

--------------------------------

### Sending 'say' Message with Transaction ID

Source: https://github.com/permaweb/ao/blob/main/lua-examples/hello-world/README.md

Demonstrates sending the 'say' message to the 'hello-world' ao process via the local `repl.js`. This message includes an Arweave transaction ID (`ao-load` parameter) and triggers a read action, returning the content of that transaction as stringified JSON.

```Shell
hello world > say bomIi0Xivq4sMA1fwAlq6nsloj1H-8qpw6oQooKDWco
```

--------------------------------

### Installing aos Command-line Tool (sh)

Source: https://github.com/permaweb/ao/blob/main/lua-examples/quest/README.md

This command installs the aos command-line tool globally using npm. The aos tool is required to send messages and interact with ao processes like Quest. Ensure Node.js and npm are installed before running this command.

```sh
npm i -g https://get_ao.g8way.io
```

--------------------------------

### Run Local Development Server with Hot Reloading Rust

Source: https://github.com/permaweb/ao/blob/main/servers/su/README.md

Starts the local development server using `systemfd` to watch for file changes and `cargo watch` to recompile and restart the `su` binary on port 9000.

```Shell
systemfd --no-pid -s http::8999 -- cargo watch -x 'run --bin su su 9000'
```

--------------------------------

### Router Scheduler List Configuration JSON

Source: https://github.com/permaweb/ao/blob/main/servers/su/README.md

Example JSON structure for the file specified by `SCHEDULER_LIST_PATH` when running the scheduler unit in `router` mode. It should contain an array of objects, each with a `url` property specifying the address of a scheduler unit.

```JSON
[
    {
        "url": "https://ao-su-1.onrender.com"
    },
    {
        "url": "https://ao-su-2.onrender.com"
    }
]
```

--------------------------------

### Logging into Docker Registry (sh)

Source: https://github.com/permaweb/ao/blob/main/dev-cli/README.md

Logs in to a Docker registry (like DockerHub) using your credentials. This is a prerequisite for pushing Docker images to the registry. Requires Docker installed.

```sh
docker login
```

--------------------------------

### Running Lua REPL with ao CLI (sh)

Source: https://github.com/permaweb/ao/blob/main/dev-cli/README.md

Starts an interactive Lua Read-Eval-Print Loop (REPL) environment using the `ao` CLI's integrated Lua runtime. Useful for quickly testing Lua syntax and small code snippets without needing a project file. Requires the `ao` CLI and Docker.

```sh
ao lua
```

--------------------------------

### Monitoring Cron Messages for a Process

Source: https://github.com/permaweb/ao/blob/main/connect/README.md

Shows how to initiate the subscription service for cron messages for a specific process using the `monitor` function. This function is used to start receiving scheduled messages for the given process.

```JavaScript
import { createSigner, monitor } from "@permaweb/aoconnect";

const result = await monitor({
  process,
  signer: createSigner(wallet),
});
```

--------------------------------

### Loading Wasm from Local File (JavaScript)

Source: https://github.com/permaweb/ao/blob/main/loader/README.md

This example demonstrates loading a Wasm binary from the local filesystem using Node.js's built-in `fs` module. It reads the file into a Node `Buffer`, which can be passed directly to the `AoLoader` because Buffer implements `ArrayBuffer`.

```JavaScript
import AoLoader from "@permaweb/ao-loader";
import fs from "fs";

async function main() {
  const wasmBinary = fs.readFileSync("process.wasm");
  const options = {
    format: "wasm32-unknown-emscripten2",
    inputEncoding: "JSON-1",
    outputEncoding: "JSON-1", 
    memoryLimit: "524288000", // in bytes
    computeLimit: 9e12.toString(),
    extensions: []
  }
  const handle = AoLoader(wasmBinary, options);
  const result = await handle(...);
}
```

--------------------------------

### Example Transfer Error Message Structure (JSON)

Source: https://github.com/permaweb/ao/blob/main/lua-examples/ao-standard-token/README.md

An example structure representing the `Transfer-Error` message that might be received if a transfer fails, for instance, due to an insufficient balance. It includes the error details within the `Tags` field.

```json
{   \n    ...,\n    Tags = {\n        Action: 'Transfer-Error,\n        ['Message-Id']: '<...>',\n        Error: 'Insufficient Balance!'\n    }\n}
```

--------------------------------

### Reading Batch of Process Results from CU

Source: https://github.com/permaweb/ao/blob/main/connect/README.md

Shows how to use the `results` function to retrieve a list of results for a given process, optionally specifying a starting cursor, sorting order, and limit. This function can be used for polling for new results.

```JavaScript
import { results } from "@permaweb/aoconnect";

let results = await results({
  process: "5SGJUlPwlenkyuG9-xWh0Rcf0azm8XEd5RBTiutgWAg",
  from: cursor,
  sort: "ASC",
  limit: 25,
});
```

--------------------------------

### Handling TransactionNotFoundError - JavaScript

Source: https://github.com/permaweb/ao/blob/main/scheduler-utils/README.md

Provides an example of how to handle potential errors when using the `locate` function, specifically catching the `TransactionNotFoundError`. It shows two methods for identifying the error type: using `instanceof` or checking the error's `name` property.

```JavaScript
import { locate, TransactionNotFoundError } from "@permaweb/ao-scheduler-utils";

await locate('<process-id>')
  .catch((err) => {
    if (err instanceof TransactionNotFoundError) // using instanceof
    if (err.name === 'TransactionNotFound') // use a static string

    throw err // bubble unknown error
  })
```

--------------------------------

### Initializing AoLoader and Spawning Process (JavaScript)

Source: https://github.com/permaweb/ao/blob/main/loader/README.md

This snippet demonstrates how to import the AoLoader, define necessary environment variables, initialize the loader with a Wasm binary and configuration options, and then use the resulting handle function to spawn a new process by passing `null` as the buffer.

```JavaScript
import AoLoader from "@permaweb/ao-loader";

/* ao READ-ONLY Env Variables */
const env = {
  Process: {
    Id: "2",
    Tags: [
      { name: "Authority", value: "XXXXXX" },
    ],
  },
};

// Create the handle function that executes the Wasm
const handle = await AoLoader(wasmBinary, {
  format: "wasm32-unknown-emscripten2",
  inputEncoding: "JSON-1",
  outputEncoding: "JSON-1", 
  memoryLimit: "524288000", // in bytes
  computeLimit: 9e12.toString(),
  extensions: []
});

// To spawn a process, pass null as the buffer
const result = await handle(null, {
  Owner: "OWNER_ADDRESS",
  Target: "XXXXX",
  From: "YYYYYY",
  Tags: [
    { name: "Action", value: "Ping" },
  ],
  Data: "ping",
}, env);
```

--------------------------------

### Run Router Binary in Docker Docker

Source: https://github.com/permaweb/ao/blob/main/servers/su/README.md

Builds a Docker image for running the `su` binary and then runs it in `router` mode, mounting the wallet file, the scheduler list JSON file, and sourcing environment variables from a `.env.router` file.

```Shell
cp .env.example .env.router
docker build -t su-runner .
docker run --env-file .env.router -v ./.wallet.json:/app/.wallet.json -v ./schedulers.json:/app/.schedulers.json su-runner router 9000
```

--------------------------------

### Run SU Binary in Docker Docker

Source: https://github.com/permaweb/ao/blob/main/servers/su/README.md

Builds a Docker image for running the `su` binary and then runs it in `su` mode, mounting the wallet file and sourcing environment variables from a `.env.su` file.

```Shell
cp .env.example .env.su
docker build -t su-runner .
docker run --env-file .env.su -v ./.wallet.json:/app/.wallet.json su-runner su 9000
```

--------------------------------

### Initializing Protocol Utilities with proto helper (JavaScript)

Source: https://github.com/permaweb/ao/blob/main/protocol-tag-utils/README.md

Demonstrates how to use the `proto` helper from `@permaweb/protocol-tag-utils` to create protocol-specific utility objects. It shows how to initialize helpers for 'ao' and 'zone' protocols and then use their methods (`value`, `values`) to extract tag data from a list of tags based on the configured protocol. Requires the `@permaweb/protocol-tag-utils` dependency. Takes a protocol name string and returns an object with protocol-aware tag utility methods.

```javascript
import { proto } from "@permaweb/protocol-tag-utils";

const ao = proto("ao");
const zone = proto("zone");

const tags = [
  { name: "Data-Protocol", value: "ao" },
  { name: "Type", value: "Process" },
  { name: "Variant", value: "ao.TN.1" },
  { name: "Data-Protocol", value: "zone" },
  { name: "Type", value: "Profile" },
  { name: "Variant", value: "0.0.2" },
];

// 'Process'
const aoType = ao.value("Type", tags);
// ['Profile']
const zoneTypes = zone.values("Type", tags);
```

--------------------------------

### Displaying Specific ao Command Help (sh)

Source: https://github.com/permaweb/ao/blob/main/dev-cli/README.md

Provides detailed help and usage information for a particular `ao` command, such as `init`, `build`, or `publish`. Replace `[command]` with the name of the command you need help with. Requires the `ao` CLI.

```sh
ao [command] --help
```

--------------------------------

### Initializing C Project (sh)

Source: https://github.com/permaweb/ao/blob/main/dev-cli/README.md

Creates and initializes a new directory for an `ao` project, specifying the `c` language template using the `-l` flag. This sets up the necessary files and structure for a C SmartWeaveContract project. Requires the `ao` CLI.

```sh
ao init -l c [myproject]
```

--------------------------------

### Run Migration CLI Shell

Source: https://github.com/permaweb/ao/blob/main/servers/su/README.md

Executes the `cli` binary's `migrate_to_disk` command with different arguments to migrate data from the database to disk, allowing migration of the entire messages table or a specific range.

```Shell
./cli migrate_to_disk 0
```

```Shell
./cli migrate_to_disk 0-1000
```

```Shell
./cli migrate_to_disk 1000
```

--------------------------------

### Using Default Configuration with connect - JavaScript

Source: https://github.com/permaweb/ao/blob/main/scheduler-utils/README.md

Explains that calling `connect()` without any configuration parameters returns an object with the default configured `validate`, `locate`, and `raw` functions, making it functionally equivalent to importing these functions directly from the library's top level.

```JavaScript
import {
 locate,
 validate,
 raw,
 connect
} from "@permaweb/ao-scheduler-utils";

// These are functionally equivalent
connect() == { validate, locate, raw }
```

--------------------------------

### Build CLI Binary with Docker Docker

Source: https://github.com/permaweb/ao/blob/main/servers/su/README.md

Builds the release binary for the `cli` utility using a Docker multi-stage build process with a specific Dockerfile (`DockerfileCli`), then extracts the compiled binary.

```Shell
docker system prune -a
docker build --target cli-builder -t cli-binary -f DockerfileCli .
docker create --name temp-container-cli cli-binary
docker cp temp-container-cli:/usr/src/cli/target/release/cli .
```

--------------------------------

### Configuring Scheduler Utils with connect - JavaScript

Source: https://github.com/permaweb/ao/blob/main/scheduler-utils/README.md

Demonstrates how to use the `connect` function to customize the configuration settings for the library, such as the GraphQL endpoint, internal cache size, redirect following, and retry parameters. It returns an object containing the configured `validate`, `locate`, and `raw` functions.

```JavaScript
import { connect } from "@permaweb/ao-scheduler-utils";

const { validate, locate, raw } = connect({
  GRAPHQL_URL: "...",
  cacheSize: 1000,
  followRedirects: true,
  GRAPHQL_MAX_RETRIES: 0,
  GRAPHQL_RETRY_BACKOFF: 300
});
```

--------------------------------

### Compile SU Binary with Docker Docker

Source: https://github.com/permaweb/ao/blob/main/servers/su/README.md

Builds the release binary for the `su` scheduler unit using a Docker multi-stage build process, then extracts the compiled binary from the container.

```Shell
docker system prune -a
docker build --target builder -t su-binary .
docker create --name temp-container su-binary
docker cp temp-container:/usr/src/su/target/release/su .
```

--------------------------------

### Initializing Signer with Browser Wallet (JS)

Source: https://github.com/permaweb/ao/blob/main/connect/README.md

Shows how to import and use the createSigner function from @permaweb/aoconnect in a browser environment. It requires an instance of globalThis.arweaveWallet as input and returns a signer function that can be passed to the connect method.

```javascript
import { createSigner } from "@permaweb/aoconnect";

const signer = createSigner(globalThis.arweaveWallet);
```

--------------------------------

### Initializing Explicit Lua Project (sh)

Source: https://github.com/permaweb/ao/blob/main/dev-cli/README.md

Creates and initializes a new directory for an `ao` project, explicitly specifying the `lua` language template using the `-l` flag. Use this to make the language choice clear or when not using the default project name. Requires the `ao` CLI.

```sh
ao init -l lua [myproject]
```

--------------------------------

### Configuring aoConnect Components

Source: https://github.com/permaweb/ao/blob/main/connect/README.md

Demonstrates using the `connect` function to configure the URLs and retry settings for the various ao components (Gateway, GraphQL, MU, CU) used by the library. This allows overriding the default component endpoints.

```JavaScript
import { connect } from "@permaweb/aoconnect";

const { spawn, message, result } = connect({
  GATEWAY_URL: "...",
  GRAPHQL_URL: "...",
  GRAPHQL_MAX_RETRIES: 2,
  GRAPHQL_RETRY_BACKOFF: 250,
  MU_URL: "...",
  CU_URL: "...",
});
```

--------------------------------

### Initializing Signer with JWK Wallet (Node.js JS)

Source: https://github.com/permaweb/ao/blob/main/connect/README.md

Shows how to import and use createSigner in a Node.js environment. It requires a JWK object, typically loaded from a file using fs, as input and returns a signer function suitable for signing DataItems and HTTP Signed Messages.

```javascript
import fs from "node:fs";
import { createSigner } from "@permaweb/aoconnect";

const wallet = JSON.parse(fs.readFileSync(process.env.PATH_TO_WALLET));
const signer = createSigner(wallet);
```

--------------------------------

### Building Project to WASM with ao CLI (sh)

Source: https://github.com/permaweb/ao/blob/main/dev-cli/README.md

Compiles the Lua or C source code of the current `ao` project into a WebAssembly (`process.wasm`) file. This process typically uses Emscripten via Docker. Requires being in an initialized `ao` project directory with source code.

```sh
ao build
```

--------------------------------

### Run Router Binary Shell

Source: https://github.com/permaweb/ao/blob/main/servers/su/README.md

Executes the pre-compiled `su` binary directly in `router` mode, listening on port 9000.

```Shell
./su router 9000
```

--------------------------------

### Run Pre-compiled SU Binary Shell

Source: https://github.com/permaweb/ao/blob/main/servers/su/README.md

Executes the pre-compiled `su` binary directly in `su` mode, listening on port 9000.

```Shell
./su su 9000
```

--------------------------------

### Sending a Message to a Process

Source: https://github.com/permaweb/ao/blob/main/connect/README.md

Demonstrates sending a message to a target ao process using the `message` function. It requires the target process ID, a signer created from a wallet, and optional parameters like anchor, tags, and data.

```JavaScript
import { createSigner, message } from "@permaweb/aoconnect";

const messageId = await message({
  process,
  signer: createSigner(wallet),
  anchor,
  tags,
  data,
});
```

--------------------------------

### Importing aoConnect Library

Source: https://github.com/permaweb/ao/blob/main/connect/README.md

Demonstrates how to import the `@permaweb/aoconnect` library using both ES Module (ESM) syntax for Node.js and browsers, and CommonJS (CJS) syntax for Node.js. It also shows a specific import path for Node.js environments when bundling with tools like Webpack.

```JavaScript
import { message, result, spawn } from "@permaweb/aoconnect";
```

```JavaScript
const { spawn, message, result } = require("@permaweb/aoconnect");
```

```JavaScript
import { createSigner, message } from "@permaweb/aoconnect/node";
```

--------------------------------

### Building ao Docker Image (sh)

Source: https://github.com/permaweb/ao/blob/main/dev-cli/README.md

Changes the current directory to the `container` subdirectory and then executes the `build.sh` script located there. This script is responsible for building the `ao` Docker image.

```sh
cd container && ./build.sh
```

--------------------------------

### Loading Wasm from Fetch (JavaScript)

Source: https://github.com/permaweb/ao/blob/main/loader/README.md

This snippet illustrates how to fetch a Wasm binary from a URL using the standard `fetch` API, commonly used for retrieving assets from the web or Arweave. It shows fetching the data and converting the response body to an `ArrayBuffer` suitable for the `AoLoader`.

```JavaScript
import AoLoader from "@permaweb/ao-loader";

async function main() {
  const tx_id = '...'
  const wasmBinary = await fetch(`https://arweave.net/${tx_id}`)
    .then(res => res.arrayBuffer())
  const options = {
    format: "wasm32-unknown-emscripten2",
    inputEncoding: "JSON-1",
    outputEncoding: "JSON-1", 
    memoryLimit: "524288000", // in bytes
    computeLimit: 9e12.toString(),
    extensions: []
  }

  const handle = AoLoader(wasmBinary, options);
  const result = await handle(...)
}
```

--------------------------------

### Executing ao Compute Unit Tests with npm

Source: https://github.com/permaweb/ao/blob/main/servers/cu/README.md

This standard npm command executes the test script defined in the project's `package.json` file. Running `npm test` initiates the unit and integration test suite, which is essential for verifying the functionality and stability of the Compute Unit implementation.

```Shell
npm test
```

--------------------------------

### Loading ao Standard Token Script in aos

Source: https://github.com/permaweb/ao/blob/main/lua-examples/ao-standard-token/README.md

Command used within the `aos` shell to load the `token.lua` script. This action initializes the current `aos` process as an `ao` Standard Token instance, implementing the specified token logic.

```sh
.load token.lua
```

--------------------------------

### Run Unit Tests for ao Unit Router - Shell

Source: https://github.com/permaweb/ao/blob/main/servers/ur/README.md

This command executes the automated unit test suite defined for the `ao` Unit Router project. Running tests helps verify the service's functionality and identify potential issues during development or before deployment.

```Shell
npm test
```

--------------------------------

### Locating Scheduler with Hint - JavaScript

Source: https://github.com/permaweb/ao/blob/main/scheduler-utils/README.md

Shows how to use the `locate` function providing both the process ID and a `schedulerHint` (the scheduler owner's wallet address). This allows the library to skip the gateway query for the scheduler tag and directly look up the `Scheduler-Location` record.

```JavaScript
import { locate } from "@permaweb/ao-scheduler-utils";

let { url, address } = await locate('<process-id>', 'scheduler-owner-id');
```

--------------------------------

### Tagging Docker Image for Publishing (sh)

Source: https://github.com/permaweb/ao/blob/main/dev-cli/README.md

Assigns a new tag to an existing local Docker image identified by `<image_id>`. The new tag includes the target repository and a version or tag (`<tag>`), preparing it for pushing to a Docker registry. Requires Docker.

```sh
docker tag <image_id> p3rmaw3b/ao:<tag>
```

--------------------------------

### Run Unit Tests Rust

Source: https://github.com/permaweb/ao/blob/main/servers/su/README.md

Executes all unit tests defined within the Rust project using the standard Cargo test runner.

```Shell
cargo test
```

--------------------------------

### Importing Core Scheduler Utils (ESM) - JavaScript

Source: https://github.com/permaweb/ao/blob/main/scheduler-utils/README.md

Imports the `locate`, `validate`, and `raw` functions from the `@permaweb/ao-scheduler-utils` library using ECMAScript module syntax, suitable for both Node.js and browser environments configured as `type: module`.

```JavaScript
import { locate, validate, raw } from "@permaweb/ao-scheduler-utils";
```

--------------------------------

### Executing Lua File with ao CLI (sh)

Source: https://github.com/permaweb/ao/blob/main/dev-cli/README.md

Runs a specific Lua file (`file.lua`) using the `ao` CLI's Lua execution capability. This is great for testing standalone Lua modules or scripts before they are integrated into a SmartWeaveContract. Requires the `ao` CLI and Docker.

```sh
ao run [file.lua]
```

--------------------------------

### Publishing WASM to Permaweb with ao (sh)

Source: https://github.com/permaweb/ao/blob/main/dev-cli/README.md

Uploads a compiled WebAssembly file (`file.wasm`) to the Arweave Permaweb as a SmartWeave Contract. Requires specifying the path to a wallet file (`-w`) for transaction funding and supports adding multiple tags (`-t`). Requires the `ao` CLI.

```sh
ao publish [file.wasm] -w [wallet] -t [name:value] -t [name:value]
```

--------------------------------

### Signing a Message for Later Dispatch

Source: https://github.com/permaweb/ao/blob/main/connect/README.md

Shows how to prepare and sign an ao message using `signMessage`. This function creates a signed message object without immediately sending it, allowing for later dispatch using `sendSignedMessage`.

```JavaScript
import { createSigner, signMessage } from "@permaweb/aoconnect";

const signedMessage = await signMessage({
  process,
  signer: createSigner(wallet),
  anchor,
  tags,
  data,
});
```

--------------------------------

### Retrieving Raw Scheduler URL - JavaScript

Source: https://github.com/permaweb/ao/blob/main/scheduler-utils/README.md

Shows how to use the `raw` function to directly retrieve the URL from the `Scheduler-Location` record associated with a specific wallet address. It requires importing `raw` and returns an object containing the `url`.

```JavaScript
import { raw } from "@permaweb/ao-scheduler-utils";

const { url } = raw('<wallet-address>')
```

--------------------------------

### Locating Scheduler by Process ID - JavaScript

Source: https://github.com/permaweb/ao/blob/main/scheduler-utils/README.md

Demonstrates how to use the `locate` function to find the scheduler's URL and address for a given `ao` process ID. It requires importing `locate` and is an asynchronous operation that returns an object containing `url` and `address`.

```JavaScript
import { locate } from "@permaweb/ao-scheduler-utils";

let { url, address } = await locate('<process-id>');
```

--------------------------------

### Implementing Custom Signer with Remote Vault (JS)

Source: https://github.com/permaweb/ao/blob/main/connect/README.md

Demonstrates how to create a custom signer function that interacts with a hypothetical remote vault service for signing. It utilizes the create function provided by aoconnect to generate the data base before sending it to the external service and then returns the signature and address.

```javascript
import { connect } from 'aoconnect'

const myAwesomeSigner = async (create) => {
  /**
   * First retrieve the public key information,
   * and invoke create to produce the signature base
   */
  const dataToSign = await fetch('https://my.vault.io/.well-known/jwks.json')
    .then((res) => res.json())
    .then(async ([firstKey]) => {
      const publicKey = Buffer.from(firstKey.n, 'base64url')
      return create({ publicKey })
    })

  /**
   * Now sign the data
   */
  return fetch(
    'https://my.vault.io',
    {
      method: 'POST',
      body: dataToSign,
      ...
    }
  ).then(async (res) => ({
    signature: res.headers.get('signature'),
    address: res.headers.get('address')
  }))
}

/**
 * Inject the signer
 */
const { message } = connect({ signer: myAwesomeSigner })
```

--------------------------------

### Minting New Tokens in ao Process (Lua)

Source: https://github.com/permaweb/ao/blob/main/lua-examples/ao-standard-token/README.md

Lua code executed in the `aos` shell to send a "Mint" message to the current process (`ao.id`), specifying the `Quantity` of new tokens to create. This action adds the specified quantity to the process's own token balance.

```lua
aos> send({ Target = ao.id, Tags = { Action = "Mint", Quantity = '10000' }})
```

--------------------------------

### Performing a Dry Run on a Process

Source: https://github.com/permaweb/ao/blob/main/connect/README.md

Illustrates how to use the `dryrun` function to simulate sending a message to a process and retrieve the result without affecting the process's state. This is useful for read operations like querying balances or process state.

```JavaScript
import { createSigner, dryrun } from "@permaweb/aoconnect";

const result = await dryrun({
  process: 'PROCESSID',
  data: '',
  tags: [{name: 'Action', value: 'Balance'},
  anchor: '1234',
  ...rest are optional (Id, Owner, etc)
});

console.log(result.Messages[0]);
```

--------------------------------

### Pushing Tagged Docker Image (sh)

Source: https://github.com/permaweb/ao/blob/main/dev-cli/README.md

Uploads a local Docker image, previously tagged as `p3rmaw3b/ao:<tag>`, to the specified remote Docker registry (e.g., DockerHub). This makes the image available remotely. Requires Docker and prior authentication (`docker login`).

```sh
docker push p3rmaw3b/ao:<tag>
```

--------------------------------

### Creating an Assignment for a Process

Source: https://github.com/permaweb/ao/blob/main/connect/README.md

Demonstrates how to use the `assign` function to create an assignment for an ao process, linking a process ID with a message ID or a base layer transaction ID. It supports optional exclusion of certain DataItem fields.

```JavaScript
import { assign } from "@permaweb/aoconnect";

const processId = await assign({
  process: "process-id",
  message: "message-id",
  exclude: ["Data", "Tags", "etc."], // optional list of DataItem fields to exclude
});
```

```JavaScript
import { assign } from "@permaweb/aoconnect";

const processId = await assign({
  process: "process-id",
  message: "txid",
  baseLayer: true,
});
```

--------------------------------

### Dispatching a Previously Signed Message

Source: https://github.com/permaweb/ao/blob/main/connect/README.md

Illustrates how to send a message that was previously signed using the `signMessage` function. The `sendSignedMessage` function takes the signed message object as input and dispatches it to the ao network.

```JavaScript
import { createSigner, sendSignedMessage } from "@permaweb/aoconnect";

const signedMessage = await sendSignedMessage(signedMessage);
```

--------------------------------

### Listing Quests (Lua - Default Format)

Source: https://github.com/permaweb/ao/blob/main/lua-examples/quest/README.md

This Lua code sends a message to the Quest process ID (Target) with the Action tag set to 'List'. This requests a list of all available quests in the default output format. Requires the aos environment and Send function.

```lua
Send({ Target = "obV9iL-w_K7DOMAV-Ze7dpgdJS3usxXdqz3mZ4Mn_zk", Tags = { Action = "List" }})
```

--------------------------------

### Manually Triggering Checkpointing via Signal

Source: https://github.com/permaweb/ao/blob/main/servers/cu/README.md

These shell commands facilitate manual checkpointing of in-memory processes by sending a signal to the running Node process. `pgrep node` or `lsof -i $PORT` are used to find the process ID, and `kill -USR2 <process>` sends the `SIGUSR2` signal, which the CU is configured to interpret as a command to checkpoint all cached processes.

```Shell
pgrep node
```

```Shell
lsof -i $PORT
```

```Shell
kill -USR2 <process>
```

--------------------------------

### Listing Quests (Lua - JSON Format)

Source: https://github.com/permaweb/ao/blob/main/lua-examples/quest/README.md

This Lua code sends a message to the Quest process ID (Target) with the Action tag set to 'List' and the Format tag set to 'json'. This requests a list of all available quests specifically formatted as JSON. Requires the aos environment and Send function.

```lua
Send({ Target = "obV9iL-w_K7DOMAV-Ze7dpgdJS3usxXdqz3mZ4Mn_zk", Tags = { Action = "List", Format = "json" }})
```

--------------------------------

### Requiring Core Scheduler Utils (CJS) - JavaScript

Source: https://github.com/permaweb/ao/blob/main/scheduler-utils/README.md

Requires the `locate`, `validate`, and `raw` functions from the `@permaweb/ao-scheduler-utils` library using CommonJS module syntax, typically used in Node.js environments configured as `type: commonjs`.

```JavaScript
const { locate, validate, raw } = require("@permaweb/ao-scheduler-utils");
```

--------------------------------

### Forging a Quest (Lua)

Source: https://github.com/permaweb/ao/blob/main/lua-examples/quest/README.md

This Lua code sends a message to the Quest process ID (Target) with the Action tag set to 'Forge'. It includes additional tags like Name, Description, Url, and Points to create a new quest or update an existing one with the same Name. Requires the aos environment and Send function.

```lua
Send({ Target = "obV9iL-w_K7DOMAV-Ze7dpgdJS3usxXdqz3mZ4Mn_zk", Tags = { Action = "Forge", Name = "Example Quest", Description = "Create a Quest", Url = "link to your site", Points = "500"}})
```

--------------------------------

### Evaluating Message on Existing Process (JavaScript)

Source: https://github.com/permaweb/ao/blob/main/loader/README.md

This code snippet shows how to use the AoLoader to evaluate a message against an existing process's state (memory buffer). It involves initializing the loader, loading the process's current memory state, invoking the handle function with the buffer and message, and handling the result, including saving the updated memory.

```JavaScript
const options = {
  format: "wasm32-unknown-emscripten2",
  inputEncoding: "JSON-1",
  outputEncoding: "JSON-1", 
  memoryLimit: "524288000", // in bytes
  computeLimit: 9e12.toString(),
  extensions: []
}
const handle = await AoLoader(wasmBinary, options);
const buffer = await LoadFromCache();

const result = await handle(buffer, {
  Owner: "OWNER_ADDRESS",
  Tags: [
    { name: "Action", value: "Balance" },
    { name: "Target", value: "vh-NTHVvlKZqRxc8LyyTNok65yQ55a_PJ1zWLb9G2JI" },
  ],
}, env);

saveToCache(result.Memory);
console.log(result.Output);
```

--------------------------------

### Retrieving Specific Target Token Balance (Lua)

Source: https://github.com/permaweb/ao/blob/main/lua-examples/ao-standard-token/README.md

Lua code executed in the `aos` shell to send a "Balance" message to the current process (`ao.id`), specifying the `Target` tag with the address of another wallet or process. It retrieves and displays the `Data` field of the last message received, showing the token balance for the specified target address.

```lua
aos> send({ Target = ao.id, Tags = { Action = "Balance", Target = '...' }})
aos> inbox[#inbox].Data
```

--------------------------------

### Initiating Token Transfer in ao Process (Lua)

Source: https://github.com/permaweb/ao/blob/main/lua-examples/ao-standard-token/README.md

Lua code executed in the `aos` shell to send a "Transfer" message to the current process (`ao.id`). It specifies the `Recipient` address and the `Quantity` of tokens to transfer. This attempts to move tokens from the sender's balance to the recipient's balance.

```lua
aos> send({ Target = ao.id, Tags = { Action = "Transfer", Recipient = '...', Quantity = '10000' }})
```

--------------------------------

### Retrieving All Token Balances in ao Process (Lua)

Source: https://github.com/permaweb/ao/blob/main/lua-examples/ao-standard-token/README.md

Lua code executed in the `aos` shell to send a "Balances" message to the current process (`ao.id`). It then retrieves and displays the `Data` field of the last message received, which contains a list or map of all known token balances managed by this process.

```lua
aos> send({ Target = ao.id, Tags = { Action = "Balances" }})
aos> inbox[#inbox].Data
```

--------------------------------

### Parsing Unassociated Tags with parseUnassoc (JavaScript)

Source: https://github.com/permaweb/ao/blob/main/protocol-tag-utils/README.md

Demonstrates the usage of `parseUnassoc` to convert the unassociated tags from a tag array into a simple JavaScript object where tag names are keys and their *first* corresponding values are the object values. Requires the `@permaweb/protocol-tag-utils` dependency. Takes a tag array and returns an object mapping unassociated tag names to single values.

```javascript
import { parseUnassoc } from "@permaweb/protocol-tag-utils";

const tags = [/*...*/];

// { Random: 'Tag', Another: 'One' }
parseUnassoc(tags);
```

--------------------------------

### Validating Scheduler Address - JavaScript

Source: https://github.com/permaweb/ao/blob/main/scheduler-utils/README.md

Illustrates the use of the `validate` function to check if a given wallet address is recognized as a valid `ao` scheduler. It requires importing `validate` and returns a boolean value (`isValid`).

```JavaScript
import { validate } from "@permaweb/ao-scheduler-utils";

const isValid = validate('<wallet-address>')
```

--------------------------------

### Concatenating Unassociated Tags with concatUnassoc (JavaScript)

Source: https://github.com/permaweb/ao/blob/main/protocol-tag-utils/README.md

Shows how to use the `concatUnassoc` function to add a list of new tags to the 'unassociated' section (before the first 'Data-Protocol' tag) of an existing tag array. Requires the `@permaweb/protocol-tag-utils` dependency. Takes an array of new tags and an existing tag array; returns a new array with the new tags appended to the unassociated section.

```javascript
import { concatUnassoc } from "@permaweb/protocol-tag-utils"

const tags = [
  { name: 'Random', value: 'Tag' }
  { name: "Data-Protocol", value: "ao" },
  { name: "Type", value: "Process" },
  { name: "Variant", value: "ao.TN.1" },
  { name: "Data-Protocol", value: "zone" },
  { name: "Type", value: "Profile" },
  { name: "Variant", value: "0.0.2" },
]

/**
[
  { name: 'Random', value: 'Tag' }
  { name: 'Another', value: 'One' },
  ...
]
 */
concatUnassoc([{ name: 'Another', value: 'One' }], tags)
```

--------------------------------

### Retrieving Current Process Token Balance (Lua)

Source: https://github.com/permaweb/ao/blob/main/lua-examples/ao-standard-token/README.md

Lua code executed in the `aos` shell to send a "Balance" message to the current process (`ao.id`) without specifying a target. It retrieves and displays the `Data` field of the last message received, showing the token balance held by the process itself.

```lua
aos> send({ Target = ao.id, Tags = { Action = "Balance" }})
aos> inbox[#inbox].Data
```

--------------------------------

### Defining Custom Signer API (TypeScript)

Source: https://github.com/permaweb/ao/blob/main/connect/README.md

Specifies the required TypeScript types for implementing a custom signer that satisfies the aoconnect API. It defines the input parameters (CreateSignatureData, SignatureDataType) and the expected output (SignatureResult) for the RawSigner function.

```typescript
type KeyPublicMeta = {
  publicKey: string;
  alg?: string;
  type?: number;
};

type CreateSignatureData = (key: KeyPublicMeta): Promise<Uint8Array>;

type SignatureDataType = "ans104" | "httpsig";

type SignatureResult = {
  signature: Uint8Array | string;
  address: string;
};

type RawSigner = (
  create: CreateSignatureData,
  type: SignatureDataType,
): Promise<SignatureResult>;
```

--------------------------------

### Retrieving Token Info in ao Process (Lua)

Source: https://github.com/permaweb/ao/blob/main/lua-examples/ao-standard-token/README.md

Lua code executed in the `aos` shell to send an "Info" message to the current process (`ao.id`). It then retrieves and displays the last message received in the process's inbox, which contains the token's name, ticker, logo, and denomination.

```lua
send({ Target = ao.id, Tags = { Action = "Info" }})
aos> inbox[#inbox]
```

--------------------------------

### Reading Single Message Result from CU

Source: https://github.com/permaweb/ao/blob/main/connect/README.md

Illustrates how to use the `result` function to fetch the evaluation output and related data for a specific message processed by an ao Compute Unit (CU). It requires the message ID and the process ID.

```JavaScript
import { result } from "@permaweb/aoconnect";

let { Messages, Spawns, Output, Error } = await result({
  message: "l3hbt-rIJ_dr9at-eQ3EVajHWMnxPNm9eBtXpzsFWZc",
  process: "5SGJUlPwlenkyuG9-xWh0Rcf0azm8XEd5RBTiutgWAg",
});
```

--------------------------------

### Parsing All Unassociated Tags with parseAllUnassoc (JavaScript)

Source: https://github.com/permaweb/ao/blob/main/protocol-tag-utils/README.md

Illustrates how to use `parseAllUnassoc` to parse the unassociated tags from a tag array into a JavaScript object. Similar to `parseUnassoc`, but the object values are arrays containing *all* corresponding values for each tag name. Requires the `@permaweb/protocol-tag-utils` dependency. Takes a tag array and returns an object mapping unassociated tag names to arrays of values.

```javascript
import { parseAllUnassoc } from "@permaweb/protocol-tag-utils";

const tags = [/*...*/];

// { Random: ['Tag'], Another: ['One'] }
parseAllUnassoc(tags);
```

--------------------------------

### Concluding a Quest (Lua)

Source: https://github.com/permaweb/ao/blob/main/lua-examples/quest/README.md

This Lua code sends a message to the Quest process ID (Target) with the Action tag set to 'Conclude' and specifies the Name of the quest to be marked as completed. Requires the aos environment and Send function.

```lua
Send({ Target = "obV9iL-w_K7DOMAV-Ze7dpgdJS3usxXdqz3mZ4Mn_zk", Tags = { Action = "Conclude", Name = "Example Quest" }})
```

--------------------------------

### Serializing Cron Object to Tags (JS)

Source: https://github.com/permaweb/ao/blob/main/connect/README.md

Illustrates how to use the serializeCron function to transform a JavaScript object representing a cron schedule and associated tags into the required tag format for the AO Data Protocol. It takes an object with 'interval' and 'tags' and returns an array of tag objects with appropriate 'Cron-' prefixes.

```javascript
import { serializeCron } from "@permaweb/aoconnect";

const cron = {
  interval: "10-minutes",
  tags: [
    { name: "Foo", value: "bar" },
    { name: "Bar", value: "foo" },
  ],
};

const tags = serializeCron(cron);
/*
  tags = [
    { name: "Cron-Interval", value: "10-minutes" },
    { name: "Cron-Tag-Foo", value: "bar" },
    { name: "Cron-Tag-Bar", value: "foo" },
  ]
*/
```

--------------------------------

### Defining Log Levels in JavaScript

Source: https://github.com/permaweb/ao/blob/main/servers/cu/README.md

This JavaScript object literal defines the logging levels used by the Compute Unit, adhering to RFC5424 severity semantics. Levels range from `error` (most important) to `silly` (least important), with corresponding numerical values. This structure is used internally for log filtering based on the configured `DEFAULT_LOG_LEVEL`.

```JavaScript
{
  error: 0,
  warn: 1,
  info: 2,
  http: 3,
  verbose: 4,
  debug: 5,
  silly: 6
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.