@inovaprog/vrtex

CLI for Vortex — manage projects and tasks from anywhere, without opening the web app.

Installation

npm install -g @inovaprog/vrtex

This installs the vortex command. The npm package is named @inovaprog/vrtex; the installed command remains vortex.

Usage

vortex login              # opens a browser (Google or GitHub)
vortex login --headless   # email and password, without a browser (SSH/VPN)
vortex logout
vortex init               # interactively links the project and prepares its devcontainer
vortex init --verbose     # also shows devcontainer startup output
vortex init --skip-tests  # refreshes project metadata without starting the local environment
vortex project use        # lists accessible projects (with IDs) and links this repository
vortex task list          # lists tasks from the linked project
vortex task create "Fix login" --priority high
vortex task status ABC-1234 progresso
vortex task update ABC-1234 --description "Updated scope"
vortex task context ABC-1234 --json # read-only implementation handoff for your coding agent
vortex task finalize-execution ABC-1234 --status success --summary "What changed and checks run" --pr-url https://github.com/owner/repo/pull/123
vortex task report-execution ABC-1234 --status success --summary "What changed and checks run" --pr-url https://github.com/owner/repo/pull/123
vortex mcp doctor         # checks login, binding, and project access
vortex mcp install        # installs the global Codex MCP bridge
vortex agent install --client codex # same bridge, discoverable as agent setup

Environment variables

| Variable | Purpose | |---|---| | VORTEX_API_URL | API base URL (default: production) | | VORTEX_GOOGLE_CLIENT_ID | Google OAuth App client ID for social sign-in | | VORTEX_GITHUB_CLIENT_ID | GitHub OAuth App client ID for social sign-in | | VORTEX_OAUTH_PORT | Local port for the social sign-in callback (default: 51763) | | VORTEX_CONFIG_DIR | Where to save local credentials (default: ~/.vortex) |

The stable task and MCP handoff commands do not require an AI provider or API key. Experimental Bound work remains a development-only dependency and is not exposed by a production CLI command.

vortex init stores only .vortex/config.json, the shareable binding between this repository and its Vortex project. It does not index source code locally.

vortex task context ABC-XXXX --json is the stable implementation handoff for Codex, Claude, Qwen, or another coding agent. It fetches and validates the task against the project linked to the repository, then emits its structured pre-refinement, acceptance criteria, and predicted files. It never indexes files, calls an AI provider, edits code, creates a branch, or changes task status.

After a Codex, Claude, or another local agent finishes implementation, prefer vortex task finalize-execution ABC-XXXX. It accepts only a task already in in_progress, records the local execution telemetry and moves a successful PR to review (or a failed delivery back to refined) — the same terminal contract used by Fargate. It refuses to reopen delivered tasks. Pass --summary and, for success, --pr-url; include --model and tokens when known.

vortex task report-execution remains available for integrations that need to record telemetry without changing the task workflow.

MCP for AI clients

Run vortex login, then vortex project use (or vortex init) in each repository. The project binding is stored in .vortex/config.json and contains only its project_id, so it is safe to commit and share with the team.

Install a global bridge once per client, then restart the client:

vortex mcp install --client codex
vortex mcp install --client claude-code
vortex mcp install --client cursor

The global entry starts vortex mcp serve in the current repository; the bridge reads the local binding and authenticates with the logged-in user's Vortex session. It never stores or sends a project API key from the repository.

The bridge also exposes get_task_context. It provides the same read-only local handoff as vortex task context, so a coding agent can implement a task using its own execution workflow.

The old .mcp.json format containing X-Project-Key is no longer accepted by the MCP endpoint. Remove it and install the CLI bridge instead. Project API keys remain available only for explicitly server-side API integrations; they are never needed by Codex, Claude, or another MCP client.

Development

npm install
npm run dev -- login --headless   # runs directly from src/, without building
npm test
npm run build                     # generates dist/