Corelayer CLI

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

npm install -g @corelayer-ai/cli

Verify the install:

corelayer --version

Authenticate

corelayer login

This flow:

Opens the Corelayer app in your browser
Asks you to authorize CLI access for your current organization
Redirects back to a temporary localhost callback used by the CLI
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.

export CORELAYER_API_KEY=cl_live_...
export CORELAYER_API_URL=https://api.corelayer.com
corelayer issues list --group <group-id>

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:

CORELAYER_API_KEY environment variable (highest priority)
Token stored in ~/.corelayer/config.json (from corelayer login)

To save an existing API key to the CLI config file without opening a browser — useful for self-hosted instances:

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:

Corelayer CLI - Manage groups, issues, and integrations from your terminal

USAGE:
  corelayer [global options] <command> [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 <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 <command> --help' for more information on a command.

Pass --help to any subcommand for its specific flags and examples:

corelayer issues --help
corelayer issues list --help

Quick Tour

A typical first session looks like:

corelayer groups list --json
corelayer config set default-group <group-id>
corelayer issues list --status Open
corelayer issues get <issue-id-or-slug> --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:

corelayer issues get <issue-id> --json
corelayer issues get <issue-slug> --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:

corelayer issues diff --group <group-id> --since 2026-06-04T20:00:00Z --json

Diff over a relative duration:

corelayer issues diff --group <group-id> --duration 2hours --limit 50 --json

If you have a default group configured, you can omit --group:

corelayer config set default-group <group-id>
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 <n> and --page <n> 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. 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):

corelayer preflight

Override any piece, include the diff, or emit JSON:

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 <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.

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

Set CORELAYER_API_KEY and CORELAYER_API_URL in the agent’s environment
Prefer --json when an agent needs to read the output
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 <group-id>
corelayer config set api-url <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 <issue-id> --feedback "..."
corelayer issues bulk-close --group <group-id> --last-seen-before-or-on 14days --feedback "..."
corelayer issues reopen <issue-id>
corelayer issues delete <issue-id> --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 <issue-id-or-slug> --json

Recommended Agent Workflows

Investigate issues in one group

corelayer groups list --json
corelayer config set default-group <group-id>
corelayer issues list --json --status Open
corelayer issues get <issue-id-or-slug> --json
corelayer issues diff --duration 2hours --limit 50 --json

Review integrations for a group

corelayer integrations list --json --group <group-id>

Summarize current issue health

corelayer issues summary --group <group-id>

Preflight a change before opening a PR

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:

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 <group-id>`.
- Prefer `corelayer issues list --json`, `corelayer issues get <issue-id-or-slug> --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

Copy the URL printed by corelayer login and open it manually in your browser.

Callback Fails on `127.0.0.1`

Use manual login:

corelayer login --code <AUTH_CODE> --api-url <server-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:

corelayer config get api-url

Then either:

run corelayer login again
or override the server for a command with --api-url <url>

Need help? Contact support for assistance with the Corelayer CLI.

Get Started

Anomaly Detection

Organization Memory

Security & Privacy

Integrations

Developer Tools

Overview

Prerequisites

Install

Authenticate

Environment Variable (Non-Interactive)

Usage

Quick Tour

Issue Lookup

Issue Diffing

Preflight

Global Flags

Environment Variables

Dedicated Deployments

Using the CLI with AI Agents

Authentication for Agents

General Best Practices

Command Types

1. Read-Only Commands

2. Local State Commands

3. Write and Update Commands

Recommended Agent Workflows

Investigate issues in one group

Review integrations for a group

Summarize current issue health

Preflight a change before opening a PR

Troubleshooting

Callback Fails on `127.0.0.1`

Wrong Organization or Server

API Calls Fail After Switching Environments

​Overview

​Prerequisites

​Install

​Authenticate

​Browser Login (Interactive)

​Environment Variable (Non-Interactive)

​Pipe a Token (Non-Interactive Login)

​Usage

​Quick Tour

​Issue Lookup

​Issue Diffing

​Preflight

​Global Flags

​Environment Variables

​Dedicated Deployments

​Using the CLI with AI Agents

​Authentication for Agents

​General Best Practices

​Command Types

​1. Read-Only Commands

​2. Local State Commands

​3. Write and Update Commands

​Recommended Agent Workflows

​Investigate issues in one group

​Review integrations for a group

​Summarize current issue health

​Preflight a change before opening a PR

​Troubleshooting

​Browser Login Does Not Open

​Callback Fails on 127.0.0.1

​Wrong Organization or Server

​API Calls Fail After Switching Environments

Overview

Prerequisites

Install

Authenticate

Browser Login (Interactive)

Environment Variable (Non-Interactive)

Pipe a Token (Non-Interactive Login)

Usage

Quick Tour

Issue Lookup

Issue Diffing

Preflight

Global Flags

Environment Variables

Dedicated Deployments

Using the CLI with AI Agents

Authentication for Agents

General Best Practices

Command Types

1. Read-Only Commands

2. Local State Commands

3. Write and Update Commands

Recommended Agent Workflows

Investigate issues in one group

Review integrations for a group

Summarize current issue health

Preflight a change before opening a PR

Troubleshooting

Browser Login Does Not Open

Callback Fails on `127.0.0.1`

Wrong Organization or Server

API Calls Fail After Switching Environments