CLI reference

> For anyone who needs the exact commands, flags and exit behavior: the agent-taskbay launcher, every npm run script, and the operational > scripts under scripts/.

Agent Taskbay is pre-1.0 (package version 0.2.0) and is published to npm. In a git checkout run the launcher as node bin/agent-taskbay.mjs after npm run build; the npx agent-taskbay form below runs the published package. Flags and script names may change between minor versions.

Requirements: Node.js 22.19.0 or newer (see Compatibility).

On this page: agent-taskbay · npm scripts · worker:tasks · db:projections:rebuild · auth:provision · security:credentials · Fixture agent script · HTTP verification scripts · Limits

agent-taskbayCopy Anchor Link

The launcher starts the production server with an embedded database, a generated credential-vault key and a development administrator, bound to loopback. It exists so you can try the console with one command. It is not a production deployment tool.

npx agent-taskbay

SynopsisCopy Anchor Link

agent-taskbay [start] [options]     Start the console (default command)
agent-taskbay demo-agent [port]     Serve sample A2A agents to connect to the console
agent-taskbay --version | --help

Options for startCopy Anchor Link

By default a browser tab opens when standard output is a terminal and the CI variable is not set.

Every A2A_* variable in Configuration may be supplied through the environment; values you set win over the launcher's defaults (listed here). Setting A2A_AUTH_MODE=oidc or A2A_OIDC_ISSUER turns off local mode, and then non-loopback hosts are allowed.

What it doesCopy Anchor Link

1. Refuses to start if the package has no production build (.next/BUILD_ID). The published package ships one; in a checkout run npm run build.
2. Creates the data directory (mode 0700) and, on first run, secrets.json (mode 0600) holding a random vault key. If the file exists but is invalid it stops instead of replacing it, because replacing the key would make stored agent credentials unreadable.
3. Writes <data-dir>/agent-taskbay.pid. A second launch on the same directory fails while the first process is alive.
4. Runs next start on the chosen port and host and waits up to 120 seconds for GET /api/auth/session to answer with a status below 500.
5. Prints the URL and data directory, then optionally opens the browser. If the server is not ready within 120 seconds the launcher prints no banner but keeps waiting on the server process.

Press Ctrl+C (SIGINT) or send SIGTERM to stop. The launcher forwards the signal, removes the pid file and exits with the server's exit code.

Exit behaviorCopy Anchor Link

A stale pid file whose process is gone is ignored and overwritten.

agent-taskbay demo-agent [port]Copy Anchor Link

Starts the repository's sample A2A agents (scripts/fixture-form-agent.mjs) on 127.0.0.1, default port 4010, and prints one Agent Card URL per variant:

The script also serves other variants used by tests (plain, invalid, unknown, rogue) that are not printed. These agents are test fixtures, not examples of production agents. Stop with Ctrl+C (exit 0). The console must be allowed to reach loopback addresses, which local mode does by default.

npm scriptsCopy Anchor Link

Run from the repository root. Pass extra arguments after --.

The db:* scripts read the database settings from the shell environment (A2A_DATABASE_PROFILE, A2A_DATABASE_URL, A2A_PGLITE_DATA_DIR) and do not load .env files.

npm run worker:tasksCopy Anchor Link

Runs the background loops (command dispatch, task subscriptions, push, reconciliation, freshness, decision/escalation sweep, notifications) in a process of their own. Use it with A2A_COMMAND_WORKER_MODE=external on the web processes.

npm run worker:tasks

npm run db:projections:rebuildCopy Anchor Link

Rebuilds the stored task projections from the event ledger, one task at a time. Safe to re-run; it resumes by task.

npm run db:projections:rebuild -- --offline-pglite

Output is one line per task, Rebuilt task <id> with projector 2., and a final Rebuilt N task projections. Re-running safely resumes by task. Failure throws and exits non-zero. Messages you may see: Stop the PGlite web process, then pass --offline-pglite; ..., Apply pending database migrations before rebuilding., No local organization; specify --organization UUID., Unknown task in organization. Any other argument that is not one of the flags above or a UUID is a usage error.

npm run auth:provisionCopy Anchor Link

Creates or updates the person-to-organization mapping that OIDC sign-in needs. Identities are matched by exact issuer and subject; e-mail and provider claims are never used.

npm run auth:provision -- --issuer https://idp.example.com --subject 00u1abcd --organization acme --name "Ada Lovelace" --role admin

On success it prints Identity membership provisioned. On bad or missing flags it throws the usage line and exits non-zero. The script reads A2A_DATABASE_* from the shell and does not check for pending migrations, so apply migrations first.

npm run security:credentialsCopy Anchor Link

Stores, revokes or re-encrypts the credential Agent Taskbay uses to call one agent. Secrets are read from standard input and are never printed.

npm run security:credentials -- --organization acme --agent 3f0c8f0e-0000-4000-8000-000000000000 --action store < binding.json

The store binding is JSON of this shape (one of four credential types):

{
  "origins": ["https://agents.example.com"],
  "credential": { "type": "bearer", "token": "REPLACE_WITH_TOKEN" }
}

origins holds 1 to 20 exact HTTPS origins the credential may be sent to. credential.type is bearer (token), apiKey (name header, value), oauthClient (issuer, tokenEndpoint, clientId, clientSecret, optional scope; client-credentials grant) or mtls (cert, key, optional ca). Secrets must be 8 to 100,000 characters. Details: Agent credentials.

Every failure prints the same line, Credential update failed. Check the organization/agent, vault key configuration and stdin binding format. No secret values are printed., and exits 1, so check the usual causes in that order: pending migrations, unknown organization or agent, vault variables, JSON shape. Success prints Agent credential binding updated.

Fixture agent scriptCopy Anchor Link

node scripts/fixture-form-agent.mjs [port] starts the same sample agents as demo-agent (default port 4010) and prints the form, plain and invalid card URLs. It is shipped in the package for demonstrations and is used by the HTTP verification scripts. The agent author guide walks through it: Build an agent for Taskbay.

node scripts/fixture-content-agent.mjs [port] (default port 4011) starts a streaming sample agent that sends content under the wrong media type: Markdown and JSON as text/plain, JSON labelled text/html, an HTML page labelled text/markdown, and the other cases in scripts/fixtures/mislabeled-content.json, each with the view the console should choose. Send it results (the default: one result artifact per case), reply (every case in the final reply), progress (every case as a status update), tools (tool calls, results, reasoning and other JSON in the shapes Google ADK, OpenAI, Anthropic, the Vercel AI SDK and MCP use), long (700-line content in a status update, a tool result and a result artifact) or a case id such as plain-json. It is a development fixture and is not shipped in the package; src/lib/mislabeled-content.test.tsx runs the same cases.

HTTP verification scriptsCopy Anchor Link

npm run test:http runs these in order. Each starts a real production server on a private port (overridable; see Development setup) with a temporary database and fixture agents, then asserts behavior over HTTP: verify-service-security, verify-task-http, verify-identity-http, verify-decisions-http, verify-workflow-http, verify-notifications-http, verify-forms-http, verify-agui-http, verify-a2ui-http, verify-agent-approvals-http and verify-phase6-exit-http. They need a completed npm run build and, for the PostgreSQL variants, A2A_TEST_POSTGRES_URL. A non-zero exit means an assertion failed.

LimitsCopy Anchor Link

• The launcher is single-user and single-process. It cannot run PostgreSQL profiles with local mode on a shared host, and it has no daemon or service mode.
• There is no agent-taskbay command for provisioning, credentials or migrations; those are repository scripts, so a production deployment needs the source tree (or a build of it) with its dependencies installed.
• Scripts that open PGlite directly require the web server to be stopped.

RelatedCopy Anchor Link

• Configuration reference
• Quickstart
• Running and workers
• Upgrading and backups