# Install OWL Compose for your Agent

Service for this installation: https://owlcompose.com
Use this exact service for setup, resume and status. Never silently switch environments or accounts.

## Task and boundaries

Complete installation, account connection and verification for the Agent running you.
Use terminal tools. If unavailable, explain that the user needs an Agent with terminal access.
Only the user completes registration, email verification, sign-in, access approval or any purchase
in their browser. Never request passwords or tokens in chat. Do not purchase automatically.

## 1. Check the environment

- macOS: x64 or ARM64.
- Windows: x64 (ARM64 uses the x64 build).
- Linux: x64 with glibc >= 2.35. Linux ARM64 and musl are not supported by the current npm release.
- Node.js in Active LTS or Maintenance LTS, with npm.
- Supported Agents include Codex, Claude Code, Cursor, Grok and OpenCode.

Run node --version and npm --version. If Node is missing, use an existing version manager or
the official supported installer, respecting host permissions. Do not replace a working Node
installation or use sudo to repair npm permissions. Report unsupported platforms accurately.

## 2. Install and start account connection

Run:

    npx --yes @owlcompose/cli@latest setup --target auto --device --no-wait --no-open --remote https://owlcompose.com

This persists the CLI as ow, installs the embedded Skill, and checks the installed files.
Replace auto with the current Agent target when known; inspect setup/agent --help for target names.
Device authorization works when the browser and CLI run on different machines.
If the latest CLI does not recognize --device, report a release mismatch and stop. Do not improvise token collection.

Valid credentials for this service are reused. Otherwise JSON output includes
status=authorization_pending, verification_uri, user_code and expires_at. Exit 0 while pending
means WAITING, not completed installation. The private device code stays in local configuration
outside the project and is never included in the displayed URL.

## 3. Connect the account

Show verification_uri and user_code to the user. They open the link, register or sign in,
compare the account and code, and allow this installation. The link works on another computer.
Keep the task pending and continue after their action. Authorization expires after 15 minutes.
If the account cannot create credentials, explain the account-access message and let the user decide.
CLI and local authoring can be installed even without hosted access; report this as partial.

Resume on the SAME Agent machine and service:

    ow setup --resume --no-wait --remote https://owlcompose.com

This polls once and saves the credential outside the project. If pending, wait at least 5 seconds
before polling again; honor slow-down responses. Omit --no-wait to wait in the CLI while keeping
the terminal session alive. A wait timeout preserves pending state. Do not start a new grant at
every poll. If denied, stop; if expired, offer a fresh authorization.
If already consumed but no credentials were saved (for example a lost response), start a fresh
authorization and let the user revoke the unused Agent installation key in their workspace.

## 4. Verify completion

    ow --version
    ow agent doctor --target auto
    ow status --remote https://owlcompose.com

Use the current Agent target for doctor. Complete means ow is runnable, the intended Agent's Skill
passes doctor, and status confirms authenticated=true for the exact service and intended account.
If can_publish=false, explain that hosted publishing is unavailable.
Do not read credential files into chat or print secrets to prove login.
Restart the Agent or open a fresh session if required to load the Skill. Doctor checks files, not
whether the current session loaded them. Do not publish a document as an installation test.
Report CLI version, Agent target, service, connected account and any remaining action.

## Update, reconnect, troubleshoot and uninstall

Update: repeat step 2. CLI and embedded Skill update together; valid credentials are reused.
Reconnect: ow setup --device --relogin --no-wait --no-open --remote https://owlcompose.com, then resume.
If ow is missing, inspect npm's global bin directory and PATH. An absolute executable path can
help when the current shell cannot yet see a newly installed command.
Distinguish connectivity errors from rejected credentials. Do not replace saved credentials just
because the service is temporarily unreachable.

    ow agent uninstall --target all
    npm uninstall --global @owlcompose/cli

Uninstall removes managed Skills and CLI, but not documents, credentials or pending login files.
Revoke unused credentials in the OWL Compose workspace.

- Installation page: https://owlcompose.com/install
- Documentation: https://owlcompose.com/docs
- CLI reference: https://owlcompose.com/docs/openwiki-cli-command-reference
- OWX reference: https://owlcompose.com/docs/for-agents/owx-reference