> ## Documentation Index > Fetch the complete documentation index at: https://docs.corelayer.com/llms.txt > Use this file to discover all available pages before exploring further. # Corelayer CLI > Install the Corelayer CLI, authenticate with your organization, and use it from the terminal or an AI agent. ## Overview The Corelayer CLI gives you terminal access to Corelayer groups, issues, and integrations. Sign in from your browser, then use Corelayer from the terminal. If your organization uses a dedicated Corelayer deployment, the CLI connects to the right server automatically. ## Prerequisites * Node.js 18+ * npm * A Corelayer account with access to at least one organization ## Install ```bash theme={null} npm install -g @corelayer-ai/cli ``` Verify the install: ```bash theme={null} corelayer --version ``` ## Authenticate ### Browser Login (Interactive) ```bash theme={null} corelayer login ``` This flow: 1. Opens the Corelayer app in your browser 2. Asks you to authorize CLI access for your current organization 3. Redirects back to a temporary localhost callback used by the CLI 4. Stores your API key and server URL in `~/.corelayer/config.json` ### Environment Variable (Non-Interactive) For CI/CD pipelines, agents, and headless environments, set the `CORELAYER_API_KEY` environment variable. No login command is required. ```bash theme={null} export CORELAYER_API_KEY=cl_live_... export CORELAYER_API_URL=https://api.corelayer.com corelayer issues list --group ``` Create an API key from the Corelayer dashboard or via the API (`POST /api/v1/api-keys`), then store it as a secret in your CI/CD platform or agent runtime. The CLI resolves credentials in this order: 1. `CORELAYER_API_KEY` environment variable (highest priority) 2. Token stored in `~/.corelayer/config.json` (from `corelayer login`) ### Pipe a Token (Non-Interactive Login) To save an existing API key to the CLI config file without opening a browser — useful for self-hosted instances: ```bash theme={null} printf '%s' "$CORELAYER_API_KEY" | corelayer login --with-token --api-url https://api.corelayer.com ``` This stores the token in `~/.corelayer/config.json` so subsequent commands work without the environment variable. ## Usage The CLI documents itself. Run `corelayer --help` to see every command: ```text theme={null} Corelayer CLI - Manage groups, issues, and integrations from your terminal USAGE: corelayer [global options] [command options] COMMANDS: login Authenticate with Corelayer (opens browser) logout Sign out and clear local credentials groups List and inspect groups issues List, inspect, and manage issues preflight Check a change against org memory before you push integrations List integrations for a group config Read and write local CLI config install-skill Install the Corelayer agent skill uninstall-skill Remove the Corelayer agent skill GLOBAL OPTIONS: --json Output as JSON for scripting -q, --quiet Suppress non-essential output --api-url Override the configured API server --no-color Disable colored output -h, --help Print help -v, --version Print version ENVIRONMENT VARIABLES: CORELAYER_API_KEY API key for non-interactive auth (skips login) CORELAYER_API_URL Server URL (default: https://api.corelayer.com) CORELAYER_AUTH_URL Auth server URL (default: https://app.corelayer.com) Run 'corelayer --help' for more information on a command. ``` Pass `--help` to any subcommand for its specific flags and examples: ```bash theme={null} corelayer issues --help corelayer issues list --help ``` ### Quick Tour A typical first session looks like: ```bash theme={null} corelayer groups list --json corelayer config set default-group corelayer issues list --status Open corelayer issues get --json corelayer issues diff --duration 2hours --limit 50 --json ``` ## Issue Lookup Use `issues get` to inspect a single issue by either its UUID or its slug: ```bash theme={null} corelayer issues get --json corelayer issues get --json ``` Slugs are useful when an issue has been copied from the Corelayer app, a customer report, or an agent summary. The JSON response includes the issue title, status, severity, root cause, next steps, trace context, and event timeline when available. ## Issue Diffing Use `issues diff` to answer what changed after a deploy, merge, or investigation window. Diff from an exact timestamp: ```bash theme={null} corelayer issues diff --group --since 2026-06-04T20:00:00Z --json ``` Diff over a relative duration: ```bash theme={null} corelayer issues diff --group --duration 2hours --limit 50 --json ``` If you have a default group configured, you can omit `--group`: ```bash theme={null} corelayer config set default-group corelayer issues diff --duration 2hours --json ``` The diff response is paginated and includes: * `since` - the timestamp used for the diff window * `issues` - issues updated or seen since that timestamp * `total` - total matching issues * `page` - current page number * `limit` - page size Use `--limit ` and `--page ` for pagination. The default limit is `20`, and the maximum limit is `100`. ## Preflight Use `preflight` to check a change against your organization's memory before opening a pull request. It returns the failure modes and things to double-check that the org has hit before for a change like this — grounded in [organization memory](/memory/overview#preflight-checking-a-change-before-you-ship). Run it inside a repository with no arguments — it derives the PR context from the current branch (repo from the git remote, title/description from commits and changed files since the base branch): ```bash theme={null} corelayer preflight ``` Override any piece, include the diff, or emit JSON: ```bash theme={null} corelayer preflight --diff corelayer preflight --base develop corelayer preflight --title "Add Redis cache" --description "Caches payment lookups" --repo payments-api corelayer preflight --json ``` Each check names the memory behind it, its severity, and how often the org has seen it; an empty result means memory had nothing relevant to flag. `--json` returns `checks` plus `consideredCount` and `pulledCount`. Preflight reads memory and is advisory — it never blocks a push. ## Global Flags The CLI supports these global flags: * `--json` for machine-readable output * `--quiet` or `-q` to suppress success messages * `--api-url ` to override the configured API server * `--no-color` to disable ANSI color output ## Environment Variables | Variable | Description | Default | | -------------------- | ---------------------------------------------- | --------------------------- | | `CORELAYER_API_KEY` | API key for non-interactive auth (skips login) | — | | `CORELAYER_API_URL` | Server URL | `https://api.corelayer.com` | | `CORELAYER_AUTH_URL` | Auth server URL for browser login | `https://app.corelayer.com` | ## Dedicated Deployments For browser login, you do not need to manually choose the API server. Corelayer returns the correct `server_url` during authorization and the CLI stores it in `~/.corelayer/config.json`. Use `--api-url` only when: * you are doing manual login with an auth code * you are testing against a local or non-default environment * you explicitly want to override the stored server URL for one command ## Using the CLI with AI Agents ### Authentication for Agents Agents should authenticate via the `CORELAYER_API_KEY` environment variable — not `corelayer login`. This follows the same pattern as `GH_TOKEN` for GitHub CLI, `VERCEL_TOKEN` for Vercel, and `STRIPE_API_KEY` for Stripe. ```bash theme={null} export CORELAYER_API_KEY=cl_live_... export CORELAYER_API_URL=https://api.corelayer.com ``` No login command is needed. The CLI reads the environment variable automatically. ### General Best Practices 1. Set `CORELAYER_API_KEY` and `CORELAYER_API_URL` in the agent's environment 2. Prefer `--json` when an agent needs to read the output 3. Set `default-group` if the agent will make repeated issue or integration calls This docs repo includes a reusable agent instruction file at `agents/corelayer-cli.md`. ### Command Types Agents should treat CLI commands in three categories: #### 1. Read-Only Commands These are safe to use for discovery, triage, and reporting: * `corelayer groups list` * `corelayer issues list` * `corelayer issues get` * `corelayer issues diff` * `corelayer issues summary` * `corelayer integrations list` * `corelayer config get` * `corelayer preflight` Best practice: * Prefer `--json` when an agent needs to reason over the output * Use `corelayer groups list --json` first if the correct group is not known * Set `default-group` before repeated issue or integration reads #### 2. Local State Commands These change the local CLI session or local config, not Corelayer data on the server: * `corelayer login` * `corelayer logout` * `corelayer config set default-group ` * `corelayer config set api-url ` Best practice: * `corelayer login` is fine when the user is actively trying to authenticate * use `corelayer config set default-group` when the user will run repeated commands against the same group * avoid changing `api-url` unless the user explicitly wants a different environment * avoid `logout` unless the user asks for it or the workflow clearly requires resetting auth #### 3. Write and Update Commands These change data or issue state on the Corelayer server and should be used carefully: * `corelayer issues close --feedback "..."` * `corelayer issues bulk-close --group --last-seen-before-or-on 14days --feedback "..."` * `corelayer issues reopen ` * `corelayer issues delete --yes` When an agent or script needs to close a large stale set, prefer `bulk-close` over looping `issues close` calls. Bulk close is the intended path for large cleanups and avoids 429 rate limits from repeated single-issue mutations. Best practice: * ask for explicit approval before running any of these commands * include a short, accurate reason when closing an issue * prefer `close` or `reopen` over `delete` * only use `delete --yes` when the user has clearly requested deletion * if the user is unsure, show the issue first with `corelayer issues get --json` ### Recommended Agent Workflows #### Investigate issues in one group ```bash theme={null} corelayer groups list --json corelayer config set default-group corelayer issues list --json --status Open corelayer issues get --json corelayer issues diff --duration 2hours --limit 50 --json ``` #### Review integrations for a group ```bash theme={null} corelayer integrations list --json --group ``` #### Summarize current issue health ```bash theme={null} corelayer issues summary --group ``` #### Preflight a change before opening a PR ```bash theme={null} corelayer preflight ``` Run this when you're about to open a pull request — it derives the change from the current branch and surfaces failure modes the org has hit before. Present any results as reminders to double-check; if it returns nothing, say memory had nothing to flag. Use it as a project instruction, repo memory, or agent prompt snippet: ```md theme={null} When you need Corelayer data, prefer the `corelayer` CLI over raw HTTP requests. - Run `corelayer groups list --json` first if the target group is unknown. - If multiple commands will use the same group, run `corelayer config set default-group `. - Prefer `corelayer issues list --json`, `corelayer issues get --json`, `corelayer issues diff --duration 2hours --json`, and `corelayer integrations list --json`. - When about to open a pull request, run `corelayer preflight` and surface anything it flags as reminders to double-check. - Treat `corelayer issues close`, `corelayer issues bulk-close`, `corelayer issues reopen`, and `corelayer issues delete --yes` as write operations that require explicit user approval. - Treat `corelayer config set` and `corelayer logout` as local state changes; use them only when the workflow clearly calls for them. - If the user is not authenticated, check if `CORELAYER_API_KEY` is set; if not, ask them to run `corelayer login` or set the environment variable. ``` This works well across agent tools. The underlying guidance is agent-agnostic rather than tied to any single coding assistant. If a specific agent supports installable skills or command packs, wrap the same instructions in that tool's native format instead of maintaining separate guidance by hand. ## Troubleshooting ### Browser Login Does Not Open Copy the URL printed by `corelayer login` and open it manually in your browser. ### Callback Fails on `127.0.0.1` Use manual login: ```bash theme={null} corelayer login --code --api-url ``` ### Wrong Organization or Server Log in again while the correct organization is active in the Corelayer app. The browser flow will return the correct server URL for that organization. ### API Calls Fail After Switching Environments Check the stored API server: ```bash theme={null} corelayer config get api-url ``` Then either: * run `corelayer login` again * or override the server for a command with `--api-url ` Need help? [Contact support](mailto:support@corelayer.com) for assistance with the Corelayer CLI.