@withandeo/cli

Developer CLI for merchant-owned customer-account applications on Andeo.

The package exposes andeo. It runs the validation and packaging commands committed by your repository, verifies the resulting portable artifact, and creates exact previews for review. Your application keeps its own framework, architecture, commerce integrations, and source repository.

The legacy @tenderprompt/accounts package retains the tender-accounts command. Existing links and login profiles keep their API origin; new Andeo logins default to https://agents.withandeo.com. No credential is transferred between origins automatically. ANDEO_* environment names are supported alongside TENDER_ACCOUNTS_*; conflicting values fail closed.

andeo.json is also accepted as the project config filename. Keep the existing schema and artifact paths during migration. If both config filenames exist, their parsed contents must agree. Maintainers can find the full rollout in docs/runbooks/ANDEO_MIGRATION.md in the platform repository.

Upload a build for manual publication

Run andeo upload --dry-run --json to validate and package locally, then andeo upload --json to retain the exact artifact in the linked app. Uploading does not create a preview or change production. The result includes the release ID, artifact digest and submitted source label.

A merchant or platform administrator can review it in Changes → Publish a retained artifact and approve production publication. This explicit approval can publish a local or PR build without a production-branch CI run. The release records manual approval separately from trusted main provenance; a local source label does not prove that the artifact matches a Git commit. Automatic source publication still requires trusted production-branch evidence.

Discover platform capabilities and guidance

andeo docs --json
andeo docs workflows
andeo capabilities --json
andeo doctor --json
andeo skill install --agent codex --force --json

docs reads version-matched bundled guides offline, without login or a checkout. The global skill installs those same references plus version/hash metadata. Review local skill edits before --force; unrelated files are preserved and symlinked owned destinations are rejected. doctor warns when the global skill differs from the CLI bundle; custom installation paths are not inspected.

capabilities is a read-only project-scoped snapshot of resource support, account enablement/quotas, caller permissions and visible service connections. It requires the matching agent API deployment. Unsupported/older servers are not interpreted as enabled: doctor reports incomplete preflight instead. Quota usage, exact service contracts and provider readiness still require delivery/start validation. doctor compares workflow source and any existing packaged resource/service declarations; run a fresh build for current artifacts.

Requirements

• Node.js 22 or newer
• an Andeo project
• an Andeo identity with developer access to the project you are changing

Install

Install the public package as a development dependency:

npm install --save-dev @withandeo/cli

Verify the installation:

npx @withandeo/cli --version
npx @withandeo/cli --help

Start from the template

The optional starter creates a merchant-owned two-service repository: a stable Shopify authentication gateway and an independently deployable React portal connected through PORTAL_UI.

Inspect the plan first, then create the project in an empty directory:

npx @withandeo/cli init --name "Acme customer account" --directory ./acme-account --dry-run --json
npx @withandeo/cli init --name "Acme customer account" --directory ./acme-account --json

The starter includes:

• Shopify Customer Account authentication with S256 PKCE;
• secure, exact-host shopper sessions;
• a React portal that receives shopper data through the gateway without holding confidential credentials;
• local development configuration and an explicit signed-out development state;
• independent tender-accounts.json contracts for the gateway and portal;
• immutable artifact packers, checks, AGENTS.md, and the bundled Andeo agent skill.

The starter does not install dependencies, initialize Git, link an Andeo project, contact Andeo, or write credentials. Existing applications do not need to use it.

Connect an existing application

Commit tender-accounts.json at the root of each independently deployable application:

{
  "schema": "tender.accounts-cli/v1",
  "commands": {
    "dev": "npm run dev",
    "check": "npm run check",
    "package": "npm run pack:tender"
  },
  "artifactDirectory": ".tender/artifacts/current",
  "returnPath": "/account"
}

The commands remain yours:

• dev starts the repository's normal local development environment;
• check runs the checks that must pass before delivery;
• package writes the portable Andeo artifact to artifactDirectory.

Run npx @withandeo/cli config example --json to print the current contract.

Authenticate and link the checkout

For a normal terminal, sign in through Andeo. Give each merchant or work context a short profile name. The CLI opens a browser, uses Authorization Code with S256 PKCE, and asks you to select one organization and the exact apps this profile may preview:

npx @withandeo/cli auth create acme

For a coding agent or headless terminal, start a device authorization instead:

npx @withandeo/cli auth create acme --device --no-open --json

Open the returned URL, approve the organization and apps, then exchange the same pending request:

npx @withandeo/cli auth status --profile acme --json

The returned pending result includes the exact profile-aware auth status command to run after approval. Refreshable profiles are stored in one private mode-0600 user file outside the repository. Set TENDER_ACCOUNTS_AUTH_FILE to choose another private location. Access tokens last 15 minutes and rotate from a 30-day login; changing the human's project access takes effect on the next refresh or request authorization check.

When an agent already knows the exact project, use that project ID as a stable profile name and authorization hint:

npx @withandeo/cli auth create prj_... --device --project prj_... --no-open --json

List local profiles without exposing their credentials:

npx @withandeo/cli auth list --json

Activate the profile for this directory tree, validate it, then link the checkout:

npx @withandeo/cli auth activate acme
npx @withandeo/cli auth status --profile acme --json
npx @withandeo/cli link --json
npx @withandeo/cli doctor --json

The activation applies to this directory and all descendants; a closer child activation wins. It is stored outside the repository, so another terminal can work in a different merchant tree at the same time without changing this one. Set TENDER_ACCOUNTS_PROFILE_BINDINGS_FILE only when a controlled environment needs another private machine-local binding file. The link stores only the API origin and exact project ID, which remains a fail-closed target guard; a link containing authProfile is rejected because repository content cannot select a local identity. For one command, set TENDER_ACCOUNTS_PROFILE=acme or pass --profile acme. If named profiles exist but neither a directory activation nor the default profile selects one, the CLI fails closed instead of guessing.

If the credential can access more than one project, select the intended project explicitly:

npx @withandeo/cli link --project prj_... --json

CI may still supply an explicitly issued TENDER_ACCOUNTS_TOKEN from its protected secret store or over standard input:

printf '%s' "$TENDER_ACCOUNTS_TOKEN" | npx @withandeo/cli auth status --token-stdin --json

Revoke the stored login when the machine should no longer have access:

npx @withandeo/cli auth delete acme --json

auth create replaces only the named profile; auth login --force replaces only the default. auth delete removes one named profile and its directory activations. Removing every profile requires the explicit auth logout --all command. Refresh, replacement, and deletion use a per-profile compare-and-swap so a late refresh cannot recreate a profile after logout. Concurrent commands may reuse a winning refresh rotation only when the stored tenant, user, and exact project grants are unchanged; a real login/logout/profile race still fails closed as auth_profile_changed and revokes any losing newly issued session.

Use Andeo-managed Git

Managed Git is available to every linked deployable project, including a protected account gateway and an independently editable service. Connect it from the app directory after authentication and linking:

npx @withandeo/cli source connect --publication preview-only --json
npx @withandeo/cli source status --json

If the repository is already connected but the developer starts in an empty workspace, authenticate to the exact project and let the CLI discover, clone, and link it:

npx @withandeo/cli source status --project prj_... --json
npx @withandeo/cli source pull --project prj_... --dry-run --json
npx @withandeo/cli source pull --project prj_... --json

The same source pull command fast-forwards an existing clean checkout when one of its remotes exactly matches the connected managed repository. It refuses dirty, detached, mismatched, paused, and non-empty non-Git workspaces. The repository credential is scoped to that one project, lives for 15 minutes, and is passed only to the Git child process; the remote URL and local link contain no credential. Merchant-hosted Git repositories remain merchant-owned and must be opened through their own Git provider before andeo link.

The CLI derives the working directory, validation command, package command, and portable artifact path from this checkout and tender-accounts.json. It adds a token-free tender Git remote by default. In a monorepo, run the command with the same --cwd used for doctor and preview.

Push the current committed revision without storing a repository credential:

npx @withandeo/cli source push --json

For repositories with reviewed changes enabled, source push uploads a bounded Git bundle through Andeo. The trusted runner verifies the exact commit and expected feature-branch ref before applying it; the CLI never receives a write credential and the default branch is protected. Repositories that have not yet enabled reviewed changes retain the legacy short-lived push credential during migration. Uncommitted files are never included. source token is read-only:

npx @withandeo/cli source token --ttl-seconds 3600 --json

Use the review flow once an administrator enables reviewed changes:

npx @withandeo/cli source push --branch feature/account-copy --json
npx @withandeo/cli source change create \
  --head feature/account-copy \
  --title "Update account copy" --json
npx @withandeo/cli source change list --state open --json
npx @withandeo/cli source change show --change scr_... --json

Andeo attaches validation, the immutable release, and exact preview to the current feature-branch snapshot. A merchant administrator opens that exact preview, approves it, and selects Land in main in the admin. Approval is invalidated if the base or head moves. Landing uses a compare-and-swap fast-forward. Landing never publishes directly; the repository's already configured default-branch policy may publish the same exact preview only after the resulting main validation succeeds. Protected gateways remain preview-only.

After landing, Andeo safely cleans up the reviewed feature branch in a separate durable workflow. Inspect branchCleanup in source change show:

• requested or running: landing succeeded and cleanup is still progressing;
• succeeded: the exact landed ref was deleted, or was already absent;
• retained: Andeo kept the ref because it moved or no longer passed a safety invariant;
• failed: the landing remains complete and a merchant administrator can retry cleanup from the Andeo admin until the bounded retry budget is exhausted.

Cleanup never deletes immutable builds, releases, compositions, approvals, or audit history, and it never publishes to production. While cleanup owns the feature ref, Andeo rejects attempts to reuse it for a new reviewed change or make it the default branch.

Inspect the managed repository without cloning it:

npx @withandeo/cli source branches --json
npx @withandeo/cli source log --branch main --limit 20 --json
npx @withandeo/cli source compare --base main --head feature/account-copy --json

These commands use an ephemeral read-only credential in a temporary Git process. They report Andeo's authoritative default branch separately from the provider's create-time default and never persist or print the credential.

Before reviewed changes are enabled, a merchant source administrator can use the lower-level migration command to promote an already-previewed branch into the current default with an exact expected-SHA lease:

npx @withandeo/cli source promote \
  --head feature/account-copy \
  --expected-current <current-main-sha> \
  --dry-run --json
npx @withandeo/cli source promote \
  --head feature/account-copy \
  --expected-current <current-main-sha> \
  --idempotency-key account-copy-v1 --json

source default set changes only Andeo's default-branch metadata. The exceptional source history replace command is for repository migrations: it requires the exact repository ID, a successful preview of the proposed head, an expected current SHA, and a dry run. Andeo archives the previous target ref before an exact compare-and-swap replacement and always suppresses automatic production publication for that migration. There is no generic force-push command.

npx @withandeo/cli source history replace \
  --head app-only-main \
  --expected-current <current-main-sha> \
  --confirm src_... \
  --dry-run --json

Every source mutation returns a durable sop_ operation. Inspect it with source operation status. If a transient provider or runner failure leaves that exact operation failed or pending, resume the stored intent by ID; Andeo does not ask the caller to reconstruct branches, SHAs, or confirmation values:

npx @withandeo/cli source operation status --operation sop_... --json
npx @withandeo/cli source operation retry --operation sop_... --json

Source administration can create validation, builds, releases, and exact previews. It does not directly publish a shopper-facing composition. Protected gateways remain preview-only, and multi-repository portal/gateway work is reviewed as one exact composition after each repository produces its immutable release.

Protected gateways are always preview-only and require a merchant administrator to publish a reviewed exact composition. A service repository may be connected with --publication default-branch; that policy promotes the same successful default-branch preview without rebuilding it.

Develop and preview

Use the same loop locally or from a coding agent:

npx @withandeo/cli dev
npx @withandeo/cli check --json
npx @withandeo/cli preview --dry-run --json
npx @withandeo/cli preview --json

preview --dry-run runs the repository checks, packages the app, and verifies the complete artifact without uploading it. A normal preview creates an immutable release and returns an exact preview URL. It does not change production.

In a monorepo, target one independently deployable application with --cwd:

npx @withandeo/cli doctor --cwd apps/portal --json
npx @withandeo/cli preview --cwd apps/portal --json

One activated profile can serve independently linked descendant apps invoked with --cwd, and multiple merchant profiles can coexist safely. Each app has its own explicit .tender/link.json containing only its project guard; the machine-local directory binding selects the profile. CI may place one fallback TENDER_ACCOUNTS_TOKEN in an ignored Git-root .dev.vars, and credential discovery never searches beyond that repository boundary.

Inspect or retry a delivery

When a preview is still running, inspect it by its dly_ developer-delivery ID:

npx @withandeo/cli delivery status --delivery dly_... --json

Retry a requested or failed delivery idempotently:

npx @withandeo/cli delivery retry --delivery dly_... --json

CLI 0.12.0 includes app workflow packaging and management. CLI-created previews retain the same delivery and artifact access across automatic token refresh. Background work remains authorized only while the original login, owner and project grant remain active; logout, session expiry or revoked access stop it.

For a preview created before session tracking whose original credential has expired, its original owner can explicitly approve recovery from the linked app:

npx @withandeo/[email protected] delivery retry --delivery dly_... --reauthorize --cwd apps/gateway --json

This retains the exact artifact and delivery, records the approval, and requires current developer access to that app. It cannot replace an already tracked login, recover another owner's delivery, or publish production. If a provider write was interrupted, recovery verifies its retained upload and binding receipts; uncertain readback stays blocked rather than uploading a replacement or clearing the hold.

Open or reopen the exact preview from a completed delivery or managed source build, without rebuilding:

npx @withandeo/cli preview entries --json
npx @withandeo/cli preview open --from dly_... --return-path /account --json
npx @withandeo/cli preview open --from sbl_... --return-path /account --json

Published connections select the entry app automatically. If multiple independent entries are available, choose one with --through prj_.... This works with developer access to the previewed app; access to the entry app is not required. An administrator can disable previews on a connection. Private apps have no direct internet address, including previews, and must open through an eligible public entry. Ordinary preview checks entry availability before building and returns the exact from ID for reopening. Browser access lasts 15 minutes; opening again creates a fresh session and replaces the previous preview selection while preserving sign-in.

Do not pass a dwf_ production workflow ID to these commands. Production workflows are shown separately in Andeo Activity; a merchant administrator can resume a waiting exact publish there without rebuilding or substituting a release.

Stream runtime logs

Stream the exact preview produced by one completed developer delivery:

npx @withandeo/cli tail --delivery dly_... --json

Merchant administrators can stream the current production runtime for the linked project:

npx @withandeo/cli tail --production --status error --json

Optional filters include --status ok,error,canceled, --method GET,POST, --search TEXT, and --sampling-rate 0.25. A tail session lasts at most 15 minutes and closes on Ctrl+C. JSON mode writes one sanitized event per stdout line; lifecycle messages go to stderr.

Sanitized fetch events include correlation.rayId. When the runtime supplies native trace context, JSON output also includes correlation.traceId and correlation.spanId; human output renders the available values as ray=, trace=, and span=. The current Tail Worker contract guarantees the request Ray ID but does not guarantee trace/span IDs for every event.

Andeo resolves the sealed preview composition or current production composition server-side. The CLI never receives infrastructure account IDs, Worker names, provider credentials, or a provider WebSocket URL. Request headers are omitted, secret-shaped object fields and sensitive query parameters are redacted, events are not persisted by the relay, and session capabilities are stored only as digests. Merchant application logs can still contain sensitive values when application code logs them as unlabelled strings, so do not log credentials or customer data.

Install the coding-agent skill

The package includes a skill that teaches a fresh Codex or Claude agent how to use the repository contract and preview workflow:

npx @withandeo/cli skill install --agent codex --json
npx @withandeo/cli skill install --agent claude --json

Installation is global for the current user by default: ~/.agents/skills for Codex and ~/.claude/skills for Claude. This lets one reviewed skill serve every merchant checkout without committing a machine-specific copy to a repository.

Use --force only when you intentionally want to replace an installed copy. Use --directory PATH only when you explicitly need a custom or repository-local destination.

Production delivery

The developer CLI intentionally has no production publish command. Developer credentials can prepare and preview changes, while production publication remains controlled by the merchant's connected default-branch workflow or an authorized administrator in Andeo.

Run npx @withandeo/cli <command> --help for the layered command reference and --json for machine-readable output.