CodeApp JS CLI

cap is a thin wrapper around the local @microsoft/power-apps-cli package and does not require an external pac installation.

codeapp-js-cli supports two use cases:

1. Use it as a CLI from any terminal.
2. Add it to a project and reuse the CLI or Node.js API.

For CLI Users

Use this section if you want to run cap commands directly from a terminal.

Install Globally

Install globally:

npm install -g codeapp-js-cli

Update an existing global install:

npm install -g codeapp-js-cli@latest

run locally from cli workspace

npm run cap help

npm run treats --help as an npm flag, so use npm run cap help for the package script or npx cap --help for the local binary.

Then run the CLI from any terminal:

cap
cap-p <prompt>
cap auth
cap environment --info
cap setup

Notes:

• cap is the portable command name to document and script against.
• The package also exposes CAP as an alias for shells where you want the uppercase form.
• Global install is the right choice when you want one CLI available across multiple workspaces on the same machine.

Uninstall

npm uninstall -g codeapp-js-cli

npm uninstall codeapp-js-cli

If cap or CAP still resolves after uninstall on Windows, remove the leftover shims from %APPDATA%\npm:

Remove-Item "$env:APPDATA\npm\cap.cmd","$env:APPDATA\npm\cap.ps1","$env:APPDATA\npm\CAP","$env:APPDATA\npm\CAP.cmd","$env:APPDATA\npm\CAP.ps1","$env:APPDATA\npm\cap-p.cmd","$env:APPDATA\npm\cap-p.ps1","$env:APPDATA\npm\CAP-p.cmd","$env:APPDATA\npm\CAP-p.ps1" -Force -ErrorAction SilentlyContinue

Get-Command cap -All | Select-Object CommandType,Source,Definition | Format-List
Get-Command CAP -All | Select-Object CommandType,Source,Definition | Format-List
npm list -g codeapp-js-cli --depth=0
npm root -g

Use Without A Global Install

Run the CLI from any directory with npx:

npx --package codeapp-js-cli cap --help
npx --package codeapp-js-cli cap auth

This is useful when you want to try the CLI, run it in CI, or avoid installing it globally.

Command Guide

Core Chat

• cap starts the interactive Copilot chat session, loads the active session from dist/config/, reads prompt and instruction files from the CLI setup directory, and saves session metadata back into dist/config/*.session.json.
• cap-p <prompt> runs a one-off Copilot turn using the current CAP prompt and instruction files without creating or reusing a saved CAP session.
• Inside chat, slash commands can run CAP commands such as /model or shell commands such as /git status and /cd ...

Authentication

• cap auth starts an interactive browser login using the bundled MSAL auth provider and caches credentials locally.
• cap auth --change clears the local auth cache and forces an account-picker login.
• cap auth --logout clears the cached login.
• cap copilot launches the official GitHub Copilot CLI login flow when you press Enter in an interactive shell, or saves a token accepted by Copilot CLI when you paste one.
• cap copilot --token <githubToken> saves an explicit Copilot token.
• cap copilot --logout clears CAP-saved Copilot metadata and, on Windows, also removes bundled Copilot OAuth credentials stored by copilot login.

Model And Prompt Files

• cap model reads the live GitHub Copilot model list through @github/copilot-sdk and stores the selected model in the CLI setup workspace config.
• cap model --<publisher/model> updates the CLI-selected model without opening the picker.
• cap model --debug prints the live GitHub Copilot model source, auth identity, and available model ids seen by the current Copilot account.
• cap skills opens a bundled skill file from the installed codeapp-js/AI/skills/ folder.
• cap skills --<skill> quick-opens a matching packaged skill.
• cap instruction prints the CLI instruction file.
• cap instruction --edit opens the CLI instruction file in VS Code or the platform fallback editor.
• cap instruction --delete removes the CLI instruction file.
• cap instruction --<markdownPath> copies that Markdown file into the CLI instruction file.

Sessions And Files

• cap session lists saved chats from dist/config/, then opens the selected chat so you can continue it.
• cap session --<session> opens the matching saved chat directly.
• cap edit lists workspace files and opens the selected file in VS Code or the platform fallback editor.
• cap edit --<filePath> opens a specific file path.
• cap mockup lists HTML files under agent/, then opens the selected mockup in the default browser.
• cap mockup --<number> opens a listed mockup directly.

Power Apps Commands

• cap environment lists tenant environments, lets you filter and select one, and writes the selected environment ID to power.config.json.
• cap environment --<environmentURL> selects the environment whose Dynamics URL matches the provided URL.
• cap environment --info prints the current environment display name, Dynamics URL, and environment ID.
• cap dataverse --<table-logical-name> adds the Dataverse table data source through the bundled action layer.
• cap table creates a new Dataverse table through the Dataverse Web API using the CAP auth token, then optionally adds columns and publishes the table.
• cap table --display-name Project --plural-name Projects --field "Status:choice:New|Active|Closed" --field "Due Date:dateOnly" creates a table without opening the interactive picker.
• cap import lists code apps from the selected environment, downloads the containing solution for the selected app, extracts the CodeApp package into dist/, and copies dist/config/power.config.json back to the workspace root.
• cap flow runs power-apps list-flows --json, lets you filter and select one, then runs power-apps add-flow --flow-id <id>.
• cap flow --<flow-id> directly runs power-apps add-flow --flow-id <id>.
• cap connector --<apiName> lists connections for that connector through the bundled service layer, selects the first one, then adds it as a data source.
• cap setup copies the bundled codeapp-js/codeApp template contents into the current working directory, then prompts for the app display name and description and writes them into power.config.json.
• cap deploy copies power.config.json into dist/config/power.config.json, runs power-apps push, extracts the app ID from the returned play URL, and writes it back to power.config.json as appId. If deployment succeeds without an app ID, it prints Deployed without AppId.
• cap deploy --debugger prepends the debugger bootstrap to dist/index.js before pushing.

npx Troubleshooting

If npx cap fails with a path under %APPDATA%\npm\node_modules\codeapp-js-cli\bin\cap.js, npx is running a stale global shim instead of the package you expected.

Use one of these fixes:

# From any directory, bypass the global shim entirely
npx --package codeapp-js-cli cap --help

# Repair the broken global install on Windows
npm uninstall -g codeapp-js-cli
Remove-Item "$env:APPDATA\npm\cap.cmd","$env:APPDATA\npm\cap.ps1","$env:APPDATA\npm\CAP.cmd","$env:APPDATA\npm\CAP.ps1" -Force -ErrorAction SilentlyContinue
npm install -g codeapp-js-cli@latest

For Project Integrators

Use this section if you want codeapp-js-cli inside a repository as a dependency or you want to call its exported API.

Install As A Dependency

Install into a project:

npm install codeapp-js-cli

Use the local CLI from that project directory without a global install:

npx cap --help
npx cap auth

Install locally to test in other workspaces

npm install
npm link
Set-Location <your new workspace>
cap help

to end testing

npm unlink -g codeapp-js-cli

Or wire it into package scripts:

{
	"scripts": {
		"cap": "cap",
		"cap:setup": "cap setup",
		"cap:deploy": "cap deploy"
	}
}

Node.js API

The package root continues to export the reusable command functions from lib/cap-core.js, so existing dependency consumers are not forced to change imports.

CommonJS:

const {
	capChat,
	capEnvironment,
	capSetup,
	parseCommandInput,
} = require('codeapp-js-cli');

async function run() {
	const parsed = parseCommandInput(process.argv.slice(2));
	if (parsed.target === 'setup') {
		await capSetup();
		return;
	}

	await capEnvironment(undefined, { namedArgs: { info: true } });
	await capChat();
}

run().catch((error) => {
	console.error(error.stderr || error.stdout || error.message);
	process.exit(typeof error.code === 'number' ? error.code : 1);
});

ES modules:

import cap from 'codeapp-js-cli';

await cap.capSetup();

Compatibility Notes

• require('codeapp-js-cli') still resolves to the same lib/cap-core.js API surface.
• Deep imports such as require('codeapp-js-cli/lib/cap-core') and require('codeapp-js-cli/lib/cap-core.js') remain available for older integrations.
• The CLI entry point remains bin/cap.js, exposed through the cap and CAP executables.

Technical Details

Copilot Backend

• CAP now uses the official GitHub Copilot CLI SDK instead of the models.github.ai REST catalog and inference endpoints.
• Available models come from the active Copilot account, so the picker now follows the Copilot model surface rather than the GitHub Models PAT catalog.
• Tool execution and file changes are handled by the Copilot CLI runtime, with CAP prompting for per-action approval.

Copilot Auth Notes

• Saved Copilot sign-in is stored in the local CAP user config.
• Runtime auth prefers a Copilot CLI logged-in user, then COPILOT_GITHUB_TOKEN/GH_TOKEN/GITHUB_TOKEN, then the saved CAP token.
• CAP copilot --logout now removes CAP-saved metadata and also clears bundled Copilot OAuth state on Windows by deleting the .copilot remembered-user entries plus the matching copilot-cli/... Windows Credential Manager target.
• For environment variables, GitHub CLI auth, or explicit tokens, remove or change that source directly.
• Running CAP copilot in an interactive shell launches Copilot device login when you press Enter at the token prompt.
• If you prefer a non-interactive setup, set COPILOT_GITHUB_TOKEN, GH_TOKEN, or GITHUB_TOKEN.

Reuse Model

The command logic lives in lib/cap-core.js and is exported from the package root so other tools can build on top of the same command implementations without reimplementing shell behavior. createDataverseTable(definition, options) is exported for tools and agents that need to create tables directly. CAP chat sessions also expose a create_dataverse_table tool with friendly field type names such as text, choice, lookup, currency, file, and image.

Lean Update Flow

• Update the wrapped CLI with npm run update:power-apps-cli.
• Remove non-production packages with npm run prune:production.
• Package output stays lean because package.json whitelists only bin, lib, and README.md, while bundled assets come from the codeapp-js dependency.

Requirements

• Node.js 20+