@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 with the repository NPM_TOKEN secret.

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 are read, write, delete.

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, 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"}'] [--if-not-exists]
• Update: monoid <resource> update <id> [--field value...] [--body '...'] [--ids id1,id2]
• Delete: monoid <resource> delete <id> [--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

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 [--date YYYY-MM-DD] – Items for the day (routines, tasks, reviews). Use --routines, --tasks, --reviews to filter.
• 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).

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.