wyrdos CLI

Agent-oriented CLI for the WyrdOS HTTP API. Uses Bearer API keys against your Convex site URL or API proxy.

Install

pnpm add -g @wyrdos/cli
# or
npx @wyrdos/cli --help

From the monorepo: pnpm --filter @wyrdos/cli exec wyrdos --help after pnpm --filter @wyrdos/cli build.

Testing

1. Build and run quick checks (no API needed)

cd packages/cli
pnpm build
pnpm test

pnpm test runs --version, --help, and --help for organisations, containers, and auth. Lint and type-check:

pnpm lint
pnpm check-types

2. Run the CLI

From this package:

node dist/cli.cjs --help
node dist/cli.cjs organisations list   # needs auth

From repo root (after build):

pnpm --filter @wyrdos/cli exec wyrdos --help
pnpm --filter @wyrdos/cli exec wyrdos organisations list

3. Test with the real API (step by step)

1. Get an API token and base URL
   From your WyrdOS/Convex setup: a Bearer token and the API base URL (e.g. https://your-app.convex.site).

2. Build the CLI (if you haven’t already):

   cd packages/cli && pnpm build

3. Set credentials (pick one):

   • Environment variables:

     export WYRDOS_API_TOKEN="your_token_here"
     export WYRDOS_API_BASE_URL="https://your-deployment.convex.site"

   • Or pass them on every call:

     node dist/cli.cjs --token "your_token_here" --base-url "https://your-deployment.convex.site" ...

4. Verify auth (from packages/cli):

   node dist/cli.cjs auth check

   If this fails, double-check token and base URL (no trailing slash).

5. Call API-backed commands, e.g.:

   node dist/cli.cjs organisations list
   node dist/cli.cjs organisations list -o json
   node dist/cli.cjs containers list
   node dist/cli.cjs containers list --organisation-id org_xxx
   node dist/cli.cjs context
   node dist/cli.cjs engines summary

6. Optional: default organisation
   For org-scoped commands you can set a default so you don’t pass --organisation-id every time:

   • Put defaultOrganisationId in ~/.config/wyrdos/config.json, or
   • Pass --organisation-id <id> when you run a command.

Setup

wyrdos login
# or
export WYRDOS_API_TOKEN=...
export WYRDOS_API_BASE_URL=https://your-deployment.convex.site
wyrdos auth check

Optional default org:

# Stored in ~/.config/wyrdos/config.json with token/baseUrl

Pass --organisation-id <id> (or set in config as defaultOrganisationId) for org-scoped lists.

Output

• TTY default: table
• Non-TTY / pipes: json
• Override: -o json | table | csv

JSON errors: { "error": true, "status": number, "message": string } (table mode prints to stderr).

Empty successful responses: If the API returns no rows (e.g. []), the CLI prints a short explanation. In -o json mode that note goes to stderr so stdout stays valid JSON for scripts; use 2>&1 if you want everything in one stream.

Interactive mode: In a normal terminal (TTY), if you omit required IDs or request body fields, the CLI prompts you for them. This keeps commands fast for agents/scripts (--data, flags, positional args) while making human terminal use friendlier.

Navigator

Use nav to browse the current WyrdOS scope by domain instead of remembering IDs up front.

Path names are written like /engines, /sections, /pipelines/.... After you run wyrdos nav, type those at the prompt (with or without the leading /). To jump straight in from the shell once: wyrdos nav /engines.

If you run node dist/cli.cjs, rebuild after pulling or changing navigator code so the bundle stays in sync: cd packages/cli && pnpm build.

wyrdos nav
wyrdos nav /sections
wyrdos nav /engines
wyrdos nav /pipelines
wyrdos nav /pipelines/containers
wyrdos nav /pipelines/containers/<containerId>/pages

• wyrdos nav — landing (intro + paths; not the full section list).
• wyrdos nav /sections — domain chooser (Engines, Pipelines, Pages, …).

In a TTY:

• number — open that item
• /path or path — go to that route (e.g. /engines or engines)
• b / back — back
• q / quit — quit

Current navigator domains:

• / landing (welcome + quick paths; not the section list)
• /sections domain chooser
• /pages
• /pages/<pageId>
• /pipelines
• /pipelines/containers
• /pipelines/containers/<containerId>
• /pipelines/containers/<containerId>/pages
• /pipelines/containers/<containerId>/zones
• /pipelines/containers/<containerId>/actions
• /pipelines/zones
• /pipelines/zones/<zoneId>
• /pipelines/zones/<zoneId>/actions
• /pipelines/actions
• /pipelines/actions/<actionId>
• /engines
• /engines/summary
• /engines/goals
• /engines/values
• /engines/principles
• /engines/pillars
• /engines/risks
• /engines/context
• /context

Command layers

Spec-backed REST (see apps/api/openapi.yaml)

organisations, containers, zones, actions, pages, containers pages, master-document-types, master-documents, master-document-sections, containers master-document-types, containers master-documents, engines.

Examples:

wyrdos organisations list
wyrdos containers list --organisation-id org_xxx
wyrdos containers create
wyrdos containers update            # prompts for container id + fields in a TTY
wyrdos containers delete            # prompts for container id + delete confirmation
wyrdos actions list -o json
wyrdos pages list --search roadmap
wyrdos containers pages list <containerId>
wyrdos containers pages link <containerId> --page-id <pageId>
wyrdos engines summary
wyrdos engines context
wyrdos master-document-types list --organisation-id org_xxx
wyrdos containers master-documents list <containerId> --master-document-type-id <typeId>
wyrdos master-documents get <documentId>

Body for creates/updates: --data '{"name":"..."}'. If you omit --data in a TTY, the CLI asks questions and builds the JSON for you.

Derived / agent commands

| Command | Purpose | |--------|---------| | auth check | Token + orgs | | context | Operational snapshot | | export context | Full JSON bundle (ops + strategic) | | plan today | Active zones + due/overdue actions | | actions inbox | Overdue or undated actions | | zones status | Zones with action counts | | containers overview | Containers with zone/action counts | | pages search <q> | Name search | | pages related-to-container <id> | Linked pages | | resolve <entity> <name> | organisation, container, zone, action, page |

Regenerating spec routes

Core REST paths are listed in src/generated/routes.ts. After changing openapi.yaml, align SPEC_ROUTES (and extend Convex gateway). Run pnpm codegen in this package to sanity-check OpenAPI operation count.

Engines & pages API

These routes are implemented in Convex (api_gateway) and documented alongside OpenAPI extensions in apps/api/openapi.yaml.