@alva-ai/toolkit

Alva REST API SDK and CLI for Node.js and the browser.

• CLI — manage config, call any Alva API from your terminal
• SDK — typed TypeScript/JavaScript client for Node.js
• Browser — drop a <script> tag into plain HTML, no build step needed

Install

npm install @alva-ai/toolkit

Or install globally for the CLI:

npm install -g @alva-ai/toolkit

CLI Quick Start

Sign in with your Alva account (opens a browser, falls back to a paste-code flow for SSH / containers / headless machines):

alva auth login

auth login runs an OAuth 2.0 Authorization Code + PKCE flow. The CLI prints a URL you can open on any device; if a local default browser opens automatically the listener finishes the login with no extra step, otherwise copy the URL to another device, log in, and paste the code shown on the page back into the terminal.

Headless / no-browser environments (SSH, containers, devcontainers, etc.) are auto-detected; pass --no-browser to force the paste-code flow or --browser to force the listener flow.

alva auth login --no-browser            # force paste-code flow
alva auth login --profile staging       # save under a named profile
alva auth login --auth-url https://stg.alva.xyz --base-url https://api-llm.stg.alva.ai  # point at stg

Or, if you already have an API key from alva.ai/apikey, skip the OAuth flow and store the key directly:

alva configure --api-key alva_your_key_here

Either path writes your credentials to ~/.config/alva/config.json.

Now use any command:

# List your files
alva fs readdir --path /

# Run code
alva run --code 'return 1 + 1'

# Manage cronjobs
alva deploy list

# Manage secrets
alva secrets list

All output is JSON for easy piping:

alva fs readdir --path / | jq '.entries[].name'

Arrays JWT

alva configure auto-provisions an Arrays JWT server-side (idempotent, soft-fails on network errors — configure still exits 0). The token is stored in your sandbox secrets as ARRAYS_JWT; the CLI never handles the token string itself.

Inspect or re-run manually:

alva arrays token ensure   # sign-if-needed; returns expires_at + tier
alva arrays token status   # returns exists + renewal_needed

alva whoami also reports current JWT status under _meta.arrays_jwt.

Playbook Skills

Browse playbook templates (system + user-created) from the alva-gateway public API. Skills are namespaced <username>/<name>.

Requires user auth — run alva auth login first.

The flow is progressive:

• get returns metadata + a file listing (path + size only — no content).
• file fetches one file's content at a time.

Bulk content is intentionally not exposed at the CLI/SDK layer; agents should fetch the file listing first, then pull only the files they need.

alva skillhub list                                          # skill catalog
alva skillhub list --tag research                           # filter by tag
alva skillhub list --username alva                          # filter by author
alva skillhub tags                                          # skill tags
alva skillhub get alva/ai-digest                            # metadata + file listing
alva skillhub file alva/ai-digest README.md                 # one file's content
alva skillhub file alva/ai-digest references/api/example.md > out.md

By default output is pretty-printed for humans. Pass --json to get the raw {success, data} envelope (e.g. for piping into jq).

Playbook Discovery

Discover public playbooks with a compact, agent-friendly result shape. The trending endpoint returns identifiers and ranking context, omitting frontend-only preview fields.

alva playbooks trending --keyword scanner --tags macro,ai --sort recent --limit 5
alva playbooks trending --tag btc --cursor <cursor>

Playbook Functions

Register creator-owned functions for released playbooks to invoke through window.alva.udf. Function entry scripts must live at an absolute ALFS .js path under the creator's home directory. Viewer credit allowance is managed through the gateway REST session-user surface.

alva functions register --playbook-id 123 --function-name analyze --entry-script-path /alva/home/alice/playbooks/my-playbook/udf/analyze.js --params-schema-file ./schema.json --no-allow-charges
alva functions list --playbook-id 123
alva functions delete --playbook-id 123 --function-name analyze
alva functions invoke --playbook-id 123 --function-name analyze --params '{"ticker":"AAPL"}'
alva functions allowance create --playbook-id 123 --amount 25
alva functions allowance get --playbook-id 123
alva functions allowance list
alva functions allowance revoke --playbook-id 123

Data Skills

Browse the Arrays backend's data-skill documentation. These endpoints are public — no Alva credentials required.

alva data-skills list                            # catalog of skills
alva data-skills summary <skill>                 # endpoints table for a skill
alva data-skills endpoint <skill> <file>         # full endpoint spec

Config Resolution

The CLI resolves config in this order:

1. --api-key / --base-url flags
2. ALVA_API_KEY / ALVA_ENDPOINT environment variables
3. ~/.config/alva/config.json (or $XDG_CONFIG_HOME/alva/config.json)

Embedded CLI Dispatch

Embedded runtimes can reuse the CLI dispatcher directly without loading the Node.js CLI shell or spawning the alva binary:

import { AlvaClient } from '@alva-ai/toolkit';
import { dispatch, CliUsageError } from '@alva-ai/toolkit/dispatch';

const client = new AlvaClient({ apiKey: process.env.ALVA_API_KEY });
const result = await dispatch(client, ['account', 'whoami']);

The embedded dispatcher always exposes the purpose-built Alpi Alva command catalog. It is independent from the packaged system alva CLI. Authentication/setup, Arrays bootstrap, SDK documentation, duplicate aliases, legacy top-level groupings, and feedback submit are not part of this catalog; old Agent paths are rejected rather than aliased. Run the embedded --help for the live tree. The independent system CLI continues to expose feedback.

The embedded surface is aligned with ALFS-native tools: local-file flags such as --local-file, --file, --params-schema-file, and screenshot --out are absent. Use inline data or prepare content in ALFS before dispatching the command; Agent screenshots return image content directly. dispatch() throws CliUsageError for command-line usage errors and AlvaError for API errors. Managed commands reject unknown flags before invoking an API. trading broker is the explicit exception because argv after that nested prefix is forwarded verbatim to the venue-native Broker contract.

Node.js command-line consumers should continue to use @alva-ai/toolkit/cli, which adds config files, authentication, local files, stdio, and Undici timeout configuration around its independent terminal dispatcher. Both entries share the SDK and low-level command execution handlers, not their catalogs, parsers, or help.

SDK Usage (Node.js)

import { AlvaClient } from '@alva-ai/toolkit';

const client = new AlvaClient({ apiKey: 'alva_your_key_here' });

// List files
const entries = await client.fs.readdir({ path: '/' });

// Run code
const result = await client.run.execute({ code: 'return 1 + 1' });

// Manage cronjobs
const jobs = await client.deploy.list();

// Manage secrets
const secrets = await client.secrets.list();

Browser Usage

Add the browser bundle via a CDN:

<script src="https://unpkg.com/@alva-ai/toolkit/dist/browser.global.js"></script>
<script>
  const client = new AlvaToolkit.AlvaClient({
    viewer_token,
  });

  client.fs.readdir({ path: '/' }).then((entries) => {
    console.log(entries);
  });
</script>

Note: The Alva API must have CORS headers configured for browser requests to work from your origin.

Playbook Runtime UDFs

When the browser bundle is loaded inside an Alva playbook iframe, it also installs window.alva.udf. The runtime reads the playbook-scoped viewer token (_pbsv) from the iframe URL, removes only that sensitive query parameter, accepts parent-pushed token refreshes, and uses PBSV headers for UDF calls.

Register creator-side functions first with alva functions register; viewer HTML should call the browser runtime instead of hand-writing API fetches.

<script src="https://unpkg.com/@alva-ai/toolkit/dist/browser.global.js"></script>
<script>
  (async () => {
    const response = await window.alva.udf.call('analyze', { ticker: 'AAPL' });
    console.log(response.result, response.credits_charged_consumer);
    const functions = await window.alva.udf.list();
  })();
</script>

For quick interactive controls, mount a runtime-managed UDF button. The button is disabled until a PBSV token is present and emits DOM events for loading, result, and error states.

<div id="analyze"></div>
<script>
  const button = window.alva.udf.renderButton('#analyze', {
    functionName: 'analyze',
    params: { ticker: 'AAPL' },
    label: 'Run analysis',
  });

  button.addEventListener('alva:udf-button:result', (event) => {
    console.log(event.detail.result.result);
  });
</script>

For module users, the same runtime is available from the package root:

import { installPlaybookRuntime, udf } from '@alva-ai/toolkit';

installPlaybookRuntime();
const response = await udf.call('analyze', { ticker: 'AAPL' });

API Reference

Resources

| Resource | Methods | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | client.user | me() | | client.fs | read(), write(), rawWrite(), stat(), readdir(), mkdir(), remove(), rename(), copy(), symlink(), readlink(), chmod(), grant(), revoke() | | client.run | execute() | | client.deploy | create(), list(), get(), update(), delete(), pause(), resume() | | client.release | feed(), playbookDraft(), playbook() | | client.playbooks | trending() | | client.functions | register(), list(), delete(), invoke(), getAllowance(), listAllowances(), createAllowance(), revokeAllowance() | | client.secrets | create(), list(), get(), update(), delete() | | client.sdk | doc(), partitions(), partitionSummary() | | client.comments | create(), pin(), unpin() | | client.remix | save() | | client.screenshot | capture() |

Error Handling

import { AlvaClient, AlvaError } from '@alva-ai/toolkit';

try {
  await client.fs.read({ path: '/nonexistent' });
} catch (err) {
  if (err instanceof AlvaError) {
    console.error(err.code); // 'NOT_FOUND'
    console.error(err.status); // 404
    console.error(err.message); // 'File not found'
  }
}

CLI Commands

alva configure --api-key <key> [--base-url <url>] [--profile <name>]
alva whoami [--profile <name>]
alva auth login [--browser | --no-browser] [--profile <name>]
alva user me
alva fs <read|write|stat|readdir|mkdir|remove|rename|copy|symlink|readlink|chmod|grant|revoke>
alva run --code <code> [--entry-path <path>] [--working-dir <dir>] [--args <json> | --args-stdin] [--timeout-ms <ms>]
alva deploy <create|list|get|update|delete|pause|resume|runs|run-logs>
alva release <feed|playbook-draft|playbook>
alva playbooks <trending>
alva functions <register|list|delete|invoke|allowance>
alva secrets <create|list|get|update|delete>
alva sdk <doc|partitions|partition-summary>
alva skillhub <list|tags|get|file> [<user>/<name>] [<file>] [--tag <t>] [--username <u>] [--json]
alva data-skills <list|summary|endpoint> [<skill>] [<file>] [--json]
alva comments <create|pin|unpin>
alva notification-preferences <list|enable-session-completed|disable-session-completed>
alva remix --child-username <u> --child-name <n> --parents <json>
alva screenshot --url <url> [--selector <s>] [--xpath <x>] --out <file>
alva markets narrative --ticker <symbol>
alva markets earnings --ticker <symbol> [--event <latest-completed|next-confirmed> | --fiscal-year <year> --fiscal-quarter <Q1|Q2|Q3|Q4>]
alva trading-pairs search --symbol <ticker> [--market <market>] [--instrument-type <type>] [--underlying-type <type>] [--quote <quote>] [--json]
alva trading-pairs resolve --pair <trading-pair> [--json]
alva trading-pairs resolve --symbol <ticker> [--market <market>] [--instrument-type <type>] [--underlying-type <type>] [--quote <quote>] [--json]
alva trading <accounts|portfolio|orders|subscriptions|equity-history|risk-rules|subscribe|unsubscribe|execute|update-risk-rules>

Contributing

git clone https://github.com/alva-ai/toolkit-ts.git
cd toolkit-ts
npm install
npm test
npm run build

License

MIT