# @inovaprog/vrtex

CLI for [Vortex](https://github.com/inovaprog/vortex) — manage projects and tasks from anywhere, without opening the web app.

## Installation

```bash
npm install -g @inovaprog/vrtex
```

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

## Usage

```bash
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:

```bash
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

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