argo-wf-client

Typed TypeScript client for the Argo Workflows REST API. Generated from the upstream swagger; resource methods are hand-written on top of an internal rest-client lib that is bundled into the published package.

Same code is published to two registries under different scopes:

| Registry | Scope | Package | Stable (@latest) | Prerelease (@alpha) | Auth | | --------------- | ------------ | --------------------------- | :----------------: | :-------------------: | ------------------------------ | | npm (npmjs.org) | @argo-mcp | @argo-mcp/argo-wf-client | ✓ | — | none — public | | GitHub Packages | @odinn1984 | @odinn1984/argo-wf-client | ✓ | ✓ | GitHub token (read:packages) |

For stable releases, use whichever you prefer (npmjs is the easier install). For prerelease/alpha builds, only GitHub Packages has them.

Install — npmjs (recommended for stable)

npm install @argo-mcp/argo-wf-client

No .npmrc config needed. Stable releases only — for alpha builds, use GitHub Packages below.

Install — GitHub Packages

GitHub Packages requires auth even for reads. Point the @odinn1984 scope at the GitHub registry with a token that has read:packages — add to ~/.npmrc (user-level) or a project-level .npmrc:

@odinn1984:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

Then:

npm install @odinn1984/argo-wf-client          # newest stable release
npm install @odinn1984/argo-wf-client@alpha    # latest prerelease build

The internal workspace dependencies are bundled into the published package — nothing else to install on either registry.

Usage

Replace the import with whichever scope you installed (@argo-mcp/argo-wf-client from npmjs or @odinn1984/argo-wf-client from GitHub Packages). Example below uses the npmjs scope.

import { ArgoWorkflowsClient } from '@argo-mcp/argo-wf-client'

const client = new ArgoWorkflowsClient({
  baseUrl: 'https://argo.example.com',
  auth: { kind: 'bearer', token: process.env.ARGO_TOKEN! },
  namespace: 'argo', // default; omit and pass per-call
})

// One page
const page = await client.workflows.list('argo', { listOptions: { limit: '100' } })

// All pages, lazily (walks `continue` tokens)
for await (const wf of client.workflows.listAll('argo')) {
  console.log(wf.metadata?.name)
}

// Stream watch events
const ctrl = new AbortController()
for await (const ev of client.workflows.watch('argo', undefined, ctrl.signal)) {
  console.log(ev.type, ev.object?.metadata?.name)
}

// Stream workflow logs
for await (const entry of client.workflows.logs('hello-world-abc', 'argo')) {
  console.log(entry.content)
}

Resources

| Accessor | Service | Count | | --------------------------------- | -------------------------------- | ----- | | client.info | InfoService | 4 | | client.workflows | WorkflowService | 17 | | client.workflowTemplates | WorkflowTemplateService | 6 | | client.clusterWorkflowTemplates | ClusterWorkflowTemplateService | 6 | | client.cronWorkflows | CronWorkflowService | 8 | | client.archivedWorkflows | ArchivedWorkflowService | 7 | | client.artifacts | ArtifactService (binary) | 5 | | client.eventSources | EventSourceService | 7 | | client.sensors | SensorService | 7 | | client.events | EventService | 2 | | client.sync | SyncService | 4 |

Errors

Every failure throws a typed subclass — instanceof-narrow at the call site:

try {
  await client.workflows.get('missing', 'argo')
} catch (err) {
  if (err instanceof NotFoundError) { /* ... */ }
}

Codegen

src/generated/{schema-types,operations}.ts are produced by scripts/gen-types.ts and committed. To regenerate after updating the swagger:

bun run gen <path-to-argo-wf-swagger.json> src/generated

The script has no default swagger path — pass it explicitly.

Tests

Unit + transport-level E2E tests run against an in-process stub HTTP server:

just test                # repo-wide
bun --filter @odinn1984/argo-wf-client test

Real-server integration tests live under test-integration/ and run against an actual Argo Workflows server. To run them locally:

just integration-up      # boot k3d cluster + install Argo Workflows
just integration-test    # bun --filter @odinn1984/argo-wf-client test:integration
just integration-down    # tear down

In CI, .github/workflows/argo-wf-integration.yml runs the same recipe on PRs that touch this client or libs/rest-client, plus nightly on main.