@usemonoid/cli

MONOid REST API CLI for terminal and script use. Authenticate with an API key and run CRUD and convenience commands against MONOid.

Install

npm install -g @usemonoid/cli

Or run without installing:

npx @usemonoid/cli whoami

The package is published to npm for installation. You do not need access to the source repository to install or run it.

Release process

Publishing is automated through GitHub Actions.

1. Update packages/cli/package.json to the new version.
2. Commit and push that version bump to the default branch.
3. Push a matching tag in the form cli/vX.Y.Z.

Example:

git tag cli/v0.1.1
git push origin cli/v0.1.1

The publish workflow validates that the tag matches the CLI package version and then runs npm publish via npm Trusted Publisher (GitHub Actions OIDC), so no long-lived NPM_TOKEN repository secret is required.

For tagged releases, the workflow also uploads the packed npm tarball to the GitHub release so the packaged CLI artifact is visible separately from GitHub's default source archives.

Configure authentication

Option 1: Persist a token (interactive use)

monoid login
# Enter your API token when prompted (or: monoid login mo_xxxx)
monoid whoami   # verify

Tokens are stored in ~/.config/monoid/credentials.json.

Option 2: Environment variable (agents / CI)

export MONOID_API_TOKEN="mo_xxxx"
monoid whoami

Option 3: Per-command token

monoid --token mo_xxxx organisations list

Create API keys in MONOid (Settings > API Keys). Use the mo_-prefixed key; scopes can be coarse (read, write, delete) or resource-scoped (tasks:read, projects:write, *:read).

Base URL

Default: https://api.usemonoid.com. Override for local or custom deployment:

export MONOID_API_BASE_URL="https://api.example.com"
# or
monoid --base-url https://api.example.com organisations list

To save it once for interactive use:

monoid config set-base-url https://api.example.com
monoid config show

You can also use monoid config set-api ... and monoid --api ... as aliases.

Command pattern

Resources: organisations, containers, projects, tasks, routine-blocks, routine-templates, reviews, daily-notes.

• List: monoid <resource> list [--limit n] [--offset n] [--filter-flags...]
• Get: monoid <resource> get <id> (use <date> for daily-notes)
• Create: monoid <resource> create [--field value...] [--body '{"key":"value"}']
• Update: monoid <resource> update <id> [--field value...] [--body '...']
• Bulk update: monoid <resource> bulk-update --ids id1,id2 --body '{"field":"value"}'
• Delete: monoid <resource> delete <id>
• Bulk delete: monoid <resource> bulk-delete --ids id1,id2

Example:

monoid organisations list
monoid projects list --status active --container-id abc123
monoid tasks create --title "Ship CLI" --bucket todo --project-id xyz
monoid daily-notes get 2025-03-17
monoid routine-blocks list --date 2025-03-17
monoid routine-templates list

Convenience commands

• monoid whoami – Show current user and token scopes (and optional expiry). Use this first to confirm auth.
• monoid status – One summary: org/container/project counts, tasks by bucket, today’s routine blocks, reviews.
• monoid calendar day|week [--date YYYY-MM-DD] – Items for the day or week. With no section flags it includes routines, tasks, and reviews; with --routines, --tasks, or --reviews, it includes only the selected sections.
• monoid routine-blocks find --date YYYY-MM-DD [--name "Light Work"] – Find dated routine block ids for scheduling.
• monoid routine-templates list|get|create|update|delete – Manage reusable routine templates. routine-creator templates remains as a compatibility alias.
• monoid tasks move <id> --do-date YYYY-MM-DD --routine-block-id <id> – Schedule or move a task in one command.
• monoid tasks upsert --title "..." [--project-id ...] – Create a task unless an exact title match already exists in the selected scope.
• monoid plan day [date] – Compact day plan for agent scheduling decisions.
• monoid login [token] / monoid logout – Store or clear the token in ~/.config/monoid/credentials.json.
• monoid config show|set-base-url|unset-base-url – Inspect or persist the default API URL in ~/.config/monoid/credentials.json.
• monoid setup-agent – Print setup instructions for AI agents (env vars, whoami).

When using agents to schedule tasks into routine blocks, treat template and calendar blocks differently:

• Template routine blocks are reusable patterns (typically no concrete date).
• Calendar routine blocks are dated instances (have date).
• Task linking must target a calendar routine block id (routineBlockId); if only a template is available, create/find the dated instance first, then link.

Output format

• -o json (default when stdout is not a TTY, e.g. in scripts): machine-readable JSON.
• -o table (default in an interactive terminal): human-readable table.
• -o csv: CSV for spreadsheets or other tools.

Errors are always structured; in JSON mode they look like:

{ "error": true, "status": 401, "code": "UNAUTHORIZED", "message": "Missing or invalid token" }

Exit codes: 0 success; 1 auth/validation; 2 server/network error.

Regenerating commands from the OpenAPI spec

The resource commands are generated from the MONOid API OpenAPI spec. After changing the spec (e.g. in apps/api/spec/openapi.yaml), regenerate and rebuild:

cd packages/cli
pnpm run generate
pnpm run build

Then commit the updated src/commands/generated/index.ts (if the codegen script overwrites it) or the generated output as documented in the script.

API spec

The CLI targets the API described in the repository at apps/api/spec/openapi.yaml, and the same API is exposed at https://api.usemonoid.com (and /openapi.json for the spec).

Agent use

See SKILL.md in this package for a concise description of the CLI for AI agents: command pattern, auth, output, and monoid setup-agent.