nixelo CLI

TLDR: Published Nixelo command-line interface for issues, projects, and boards.

Status

• Package and binary name: nixelo
• Source version: see package.json
• Release verification: pnpm run cli:release:verify
• Focused tests: pnpm run test:cli:run
• Built browser smoke: pnpm run smoke:cli:built

Product Capability Discovery

The CLI is one interface to Nixelo's broader workspace: project execution, collaborative knowledge, scheduling, business operations, time and capacity, grounded AI, and developer automation. Use these public resources before assuming a workflow is CLI-only or unsupported:

• https://nixelo.com/capabilities.json - versioned product areas plus exact CLI, API-key HTTP, and hosted MCP operation support and bindings
• https://nixelo.com/llms.txt - concise product and documentation index
• https://nixelo.com/markdown/cli.md - generated CLI guide
• https://nixelo.com/markdown/api.md - generated HTTP API guide

Requirements

• Node.js >=22.12.0, matching the Commander 15 runtime requirement.
• Linux, macOS, or Windows. POSIX systems enforce mode 0700 on the config directory and 0600 on stored credentials; Windows uses its native ACL semantics.

Install And Upgrade

Run the currently published CLI without installing it globally:

npx nixelo --help
npx nixelo <command>

Install, upgrade, or uninstall the global binary with npm:

npm install --global nixelo
npm install --global nixelo@latest
npm uninstall --global nixelo

Pin an exact published version in automation instead of relying on latest, for example npx nixelo@<version> --version.

Versioning

Keep releases on 0.0.x until all of these are true:

• package publication and provenance are verified;
• login, organization identity, issue mutation, revocation, and logout pass through the built-package smoke against a disposable local target;
• command registration, help, and shell completion parity gates pass;
• the CLI HTTP API and token-scope documentation match mounted routes;
• no known P1 or P2 CLI correctness or security defect remains.

The first minor version requires a documented stable command and output contract. A major version requires an intentional incompatible contract change with migration guidance.

Run pnpm run smoke:cli:built from the repository to verify the built CLI entrypoint. The runner owns a disposable local Convex deployment and loopback app server, rejects cloud selectors, and does not contact the npm registry. Automated production mutation smoke is forbidden. Production release verification is a separate, explicitly authorized operation, not a package test command.

Authentication And Scope

nixelo login opens the app-owned /cli-auth route, receives a short-lived authorization code on its loopback callback, exchanges that code once, and stores the resulting organization-bound CLI token under ~/.config/nixelo/. Use nixelo login --admin to request admin scopes when the selected organization permits them. NIXELO_TOKEN takes precedence over local token storage.

The active token, not local config, selects the organization for every request. Run nixelo whoami to inspect it. config set --project <key> stores only a default project key within that organization; logging into another organization can require a different project key.

Command Families

nixelo login
nixelo logout
nixelo whoami
nixelo apikeys
nixelo automations
nixelo tokens
nixelo config
nixelo docs
nixelo fields
nixelo time
nixelo templates
nixelo stats
nixelo filters
nixelo issues
nixelo invites
nixelo projects
nixelo sprints
nixelo labels
nixelo notifications
nixelo teams
nixelo workspaces
nixelo webhooks
nixelo users
nixelo --version
nixelo completion bash|zsh|fish

Run nixelo --help for the complete generated command tree and nixelo <command> --help for arguments and options. Supported machine-readable output uses --json or --output json|csv where applicable. Destructive commands expose --yes for explicit non-interactive confirmation.

Team membership removal accepts exactly one selector. Use --email for normal members or --user-id when the roster entry has no resolvable user profile:

nixelo teams members remove <team-slug> --email <email> --yes
nixelo teams members remove <team-slug> --user-id <user-id> --yes

Without an explicit selector, an interactive terminal may use the existing email picker. Non-interactive use must pass one selector; --yes skips confirmation only.

Document metadata lifecycle commands use exact document IDs. Destination workspaces and teams use slugs, projects use keys, and organization creation always uses the token-bound organization:

nixelo docs create "Runbook" [--workspace <slug> | --team <slug> | --project <key>] [--parent <id>] [--public]
nixelo docs rename <id> "New title"
nixelo docs move <id> (--parent <id> | --root)
nixelo docs archive <id>
nixelo docs move-project <id> (--project <key> | --remove-project)

Hierarchy moves append at the destination and expose no raw order. The CLI intentionally has no document unarchive command and no editor, snapshot, Yjs, body, comment, lock, visibility-toggle, delete, restore, favorite, template, or version mutation. Those remain with their browser/domain owners.

Configuration

nixelo config get
nixelo config path
nixelo config set --project ENG
nixelo config clear --project

Configuration and authentication files live under ~/.config/nixelo/.

Environment Overrides

| Variable | Effect | | --- | --- | | NIXELO_TOKEN | Uses the supplied token instead of the stored credential. | | NIXELO_CONFIG_DIR | Changes the directory containing auth.json and config.json. | | NIXELO_SITE_URL | Overrides the Convex HTTP API base URL. Intended for approved development targets. | | NIXELO_AUTH_URL | Overrides the app-owned /cli-auth browser-login URL. Intended for approved development targets. |

API requests are cancelled after 30 seconds. logout succeeds when no stored credential exists, but returns a failure when an existing credential cannot be removed.

Exit Codes And Output

• Exit code 0 means the command completed successfully.
• Any nonzero exit code means invocation, validation, authentication, permission, network, or API failure. Automation should not depend on finer error-code categories during 0.0.x.
• Successful command data is written to stdout. Diagnostics and machine-output progress are written to stderr where supported, so stdout remains parseable.
• Use --json or --output json|csv for automation. Human table text is not a stable interface.
• Time start/stop/list/summary output is operational-only. It includes context, durations, billable/billed state, and completeness metadata, but never rates, currency, cost, or equity values. Use authorized financial report operations for money data.
• The CLI remains pre-stable during 0.0.x; pin the package version and validate required fields. A documented stable machine-output contract is required before the first minor release.

Development

pnpm --dir packages/cli install
pnpm --dir packages/cli run build
pnpm --dir packages/cli run typecheck
pnpm run test:cli:run

The repository and package-local test commands share the package-owned CLI test gate. It stores a private scanned Vitest log and JSON report under .local/cli-test-gate/runs/<run>/, rejects caller-owned artifact destinations, and keeps at most five completed runs within a 512 MiB aggregate budget while protecting incomplete diagnostics.