Getting started

Install the plugin in Codex or Claude Code, let it install Java and SQLcl, configure a direct SQLcl or ORDS HTTP(S) connection, then describe the change you want in the conversation. The repository and the npm package both include the built runtime, so no Git build, TypeScript compilation or npm ci is needed for installation.

This guide describes the current 2.5.0 source bundle, including APEX 26.2 partial imports. Install from the source repository for these features; check the version and capabilities of a separately published npm package. See release notes and implementation status for the current scope and qualification requirements.

Already using APEX 26.2? Start with partial imports: update a page and its shared components. Use the updated checkout runtime and the reviewed 26.2 compiler; the managed dependency installer still defaults to 26.1.

Codex Cloud

For a cloud task, follow Run APEXREST in Codex Cloud. It provides a pinned CLI bootstrap, setup/maintenance scripts and ORDS HTTPS configuration for a Linux container. Plugin registration below applies to desktop and CLI hosts; the Cloud example uses the CLI only.

Prerequisites

A clean APEX installation is enough for ordinary deployment. APEXREST service tables, utPLSQL and a provisioned sandbox are not prerequisites for an application-only import. Installation does not include Oracle binaries, browser credentials or a database account.

Install in Codex

In a terminal where Node 24 and the Codex CLI are available:

node --version
codex --version
codex plugin marketplace add apexrest-dev/apexrest
codex plugin add apexrest-apex@apexrest
codex plugin list --json

To find the installed plugin in the desktop app, open Plugins and look for APEXREST for Codex and Claude Code; use @ in the message box or $apexrest-work to invoke a skill. The plugin adds no sidebar or menu button. If the tools are not listed, see troubleshooting.

Install in Claude Code

The same bundle carries a Claude Code manifest (.claude-plugin/plugin.json, plugin name apexrest) and the repository root holds .claude-plugin/marketplace.json:

claude plugin marketplace add apexrest-dev/apexrest
claude plugin install apexrest@apexrest

For a local checkout, pass the checkout path to marketplace add; to try a checkout for one session without installing, start claude --plugin-dir <checkout>/plugins/apexrest-apex. The manifest declares the six skills and the MCP server node ${CLAUDE_PLUGIN_ROOT}/runtime/mcp.mjs; no global MCP registration is needed. The node on the PATH of the shell that starts claude must be Node.js 24 or newer. Start a new Claude Code session after installation.

Check the setup

In a new session, ask:

Use APEXREST to check my setup. Report the compiler, connection and target checks that still need attention.

The agent calls apexrest_status with detail: "doctor", which probes the host, SQLcl and Java without downloads or database calls and reports the SQLcl mode (cli or mcp) and database transport (direct or ords). A detected tool is not a validated compiler or a live connection; a successful registration or plugin listing alone does not prove that the MCP server started.

Install Java and SQLcl

Missing SQLcl or Java is a reason to install, not to stop. The setup skill ($apexrest-setup in Codex, /apexrest:apexrest-setup in Claude Code) runs the bundled installer; you can run it yourself from a checkout or the installed plugin directory:

node plugins/apexrest-apex/runtime/apexrest.mjs dependencies install --dry-run --json
node plugins/apexrest-apex/runtime/apexrest.mjs dependencies install --yes --accept-oracle-license --json

Read the preview first: it lists versions, destinations, download hosts and the Oracle terms. Run the second command only after accepting those terms; --accept-oracle-license records that separate consent. --offline uses cached downloads, --home and --cache-dir select managed storage. Tools install under ~/.apexrest (or APEXREST_HOME); a custom --home must also be set as APEXREST_HOME for later CLI and MCP processes. The installer does not provision APEX, install utPLSQL or change database connections. Rerun the doctor afterwards.

Managed runtime installation and the launcher

apexrest setup combines dependency installation with Codex registration and creates the apexrest launcher at ~/.apexrest/bin/apexrest (macOS/Linux) or apexrest.ps1 and apexrest.cmd on Windows; direct codex plugin add or claude plugin install does not create that launcher. From a reviewed checkout:

node plugins/apexrest-apex/runtime/apexrest.mjs setup --dry-run --json
node plugins/apexrest-apex/runtime/apexrest.mjs setup --yes --accept-oracle-license --json

--native-only registers the plugin with the existing runtime without downloads; --codex-home selects a Codex profile and --codex the Codex executable. A foreign or ambiguous marketplace stays blocked with MARKETPLACE_OWNERSHIP_CONFLICT. Add the launcher to PATH for future shells (APEXREST never edits shell startup files):

export PATH="$HOME/.apexrest/bin:$PATH"
apexrest --help

In PowerShell, invoke & "$env:USERPROFILE\.apexrest\bin\apexrest.ps1". npm install -g apexrest provides the same command through npm's global bin directory. Managed setup registers Codex only, but its payload contains both host manifests and marketplaces. To reuse it in Claude Code, add the native.destination returned by setup as the marketplace path, then install apexrest@apexrest. Both MCP bindings use the managed Node executable and home; Claude resolves its own cached runtime path. Direct repository installations instead inherit APEXREST_HOME from the launching shell.

Connect and configure

APEXREST stores connection references, not passwords. Choose the SQLcl mode and database transport once per managed home, then register references:

# Direct Oracle listener: map saved SQLcl connections.
apexrest sqlcl configure --mode cli --database-transport direct --json
apexrest connection list --saved --json
apexrest connection add dev-read --sqlcl-name saved-read-connection --json
apexrest connection add dev-deploy --sqlcl-name saved-deploy-connection --json
apexrest connection test dev-read --json

Saved direct connections come from SQLcl's own store; create them interactively in SQLcl first. --saved lists or tests that store without an APEXREST reference. --mode mcp selects the official SQLcl stdio server (sql -mcp) instead of the SQLcl subprocess; existing sessions keep their mode.

For ORDS HTTP(S), when the listener on port 1521 is unreachable, use the existing database account and the schema's ORDS URL. The password is read from a private local file (owner-only, not a symlink) and kept at plugin level under $APEXREST_HOME/credentials/:

apexrest connection add dev-read --ords-url https://ords.example.invalid/ords/app_user/ --ords-username app_user --password-file /path/to/local/file --json
apexrest sqlcl configure --mode cli --database-transport ords --json
apexrest connection test dev-read --json

ORDS requires cli mode. See SQL through ORDS. In the conversation, the agent registers references with apexrest_project action:connection_add (name plus sqlclName, or ordsUrl, ordsUsername and passwordFile) and checks them with connection_list and connection_test; it never asks for a password in chat.

Then give the agent the non-secret target identity for an environment:

Configure an APEXREST test environment using the connection references dev-read and dev-deploy. The workspace is YOUR_WORKSPACE, parsing schema YOUR_SCHEMA, application ID YOUR_APPLICATION_ID, database unique name YOUR_DB, service YOUR_SERVICE, and application URL https://your-host.example/ords/r/workspace/app/. Verify that the read connection matches this identity.

Replace every placeholder with the actual target. No environment is invented by project initialization. Follow configuration for the exact environment schema, task authorization and allowed origins described in the safety rules.

Create or adopt a project

For a new application, name a new or empty directory and a template:

Use APEXREST to create a blank application in a new sales-app project. Configure the identified test target, add a dashboard using real source measures, then ship it to that target and verify it in the browser.

The agent calls apexrest_project action:init with directory and template (blank-app or customer-crm); initialization generates real Oracle sources and rejects nonempty directories. For an existing application:

Use APEXREST to initialize an existing-app project in a new sales-app directory and adopt the identified test application as a working copy. Preserve all Oracle IDs, .apex metadata, unrelated pages, shared components and authentication. Add the requested dashboard, ship it into that same app and verify the result.

Adoption (action:adopt with env, appId and workingCopy) exports into a new local directory and fails rather than overwrite local edits. Keep the generated Oracle metadata under version control and reuse the working source for later changes; see existing applications. The CLI equivalents are apexrest project init DIR --template existing-app and apexrest project adopt --env dev --app-id ID --working-copy --json.

Review the target. No manual folder trust list is required. An identified DEV/QA/TEST app task authorizes its import; production deploy/restore is forbidden. Read the current safety rules before database work.

Edit, validate, ship and verify

For an existing qualified APEX 26.2 application, initialize a sync baseline before editing, then use importMode:auto to select eligible changed files or importMode:files with an explicit page/dependency list. Review importSelection.resolvedMode, selected files and any full-import reasons before applying. The partial-import guide gives matching CLI plan/apply examples and explains conflicts, backups and readback. APEX 26.1 continues to use full imports.

The work skill ($apexrest-work in Codex, /apexrest:apexrest-work in Claude Code) drives one cycle per change: inspect the project, read at most three references, edit the .apx sources and use one apexrest_ship mode:apply call to compile, plan and apply. Standalone validation is for diagnostics and a separate plan is for explicit review. Report confirmed server completion and inspect requested pages with the selected browser. Browser checks run only when requested. The steps are listed in the features page.

Your explicit request to create, update or import an identified development/test application is the authorization for the apply step. The runtime records it as a deploy grant bound to the exact project, target and plan digest, imports with a checksummed backup of an existing app, identity and drift checks, verifies and removes the grant; the agent does not ask the same permission twice. Plans expire after 30 minutes. Unrelated schema writes, authentication changes, other targets and production are outside that scope. A failed or unknown write outcome requires diagnosis or reconciliation before any retry; see deployment safety.

For a page or dashboard, the agent reconciles the read-only sources and confirmed server import. It inspects the imported page in the selected browser only when requested. Browser observations are recorded separately from compiler and import results. Application verification uses the host in-app browser. See testing.

Use the CLI

Every MCP operation has a CLI command with --json output and the same exit codes (0 success, 1 failed, 2 input, 3 dependency, 4 approval, 5 conflict, 6 unknown or cancelled). apexrest --help lists the commands; apexrest ship --help shows one command's options. There is no interactive terminal menu.

apexrest status --detail doctor --json
apexrest project inspect --project ./crm --detail summary --json
apexrest reference search metric card --corpus components --limit 3 --json
# One ordinary authorized ship call compiles and plans before applying.
apexrest ship --project ./crm --env dev --mode apply --user-request "Add the order status report to the dev app" --json
apexrest job status JOB_ID --wait-seconds 30 --project ./crm --json
# Only when browser verification was requested:
apexrest browser open --project ./crm --env dev --json

ship --mode plan validates with the Oracle compiler, reads the target and writes .apexrest/plans/ship-<id>.json for review; --mode apply and granular deploy/restore refuse production targets. The granular commands (deploy plan|apply|status|restore-plan, apex export|generate|sync|diff, jobs status|cancel, compose plan|materialize, status) remain available. The CRM template includes schema changes, so its import needs authorization for that schema scope; verify its interactions in the selected browser when requested.

When calling project-scoped MCP tools, pass the absolute application project directory as project: the MCP server starts in its plugin directory and rejects missing or relative paths. CLI examples resolve --project from the terminal's working directory.

Remove the plugin and managed tools

Codex:

codex plugin remove apexrest-apex@apexrest
codex plugin marketplace remove apexrest

Claude Code:

claude plugin uninstall apexrest@apexrest
claude plugin marketplace remove apexrest

Managed installation has its own ownership-checked commands: apexrest dependencies uninstall --yes removes recorded managed tools while preserving external runtimes, projects, backups, SQLcl connections and the download cache; apexrest plugin uninstall removes the managed Codex registration and plugin files (--keep-runtime retains them). Uninstall tools first when removing both. Start a new session after removal. Uninstalling never deletes application projects, backups, credentials, deployment history or database deployments.

Next steps

Read deployment safety before operating a target, security before sharing artifacts and the verification status before selecting this build for production work. The documentation index links every guide and evidence record.

View this page source