Skip to main content

​
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

​
Browser Login (Interactive)

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

​
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

VariableDescriptionDefault
CORELAYER_API_KEYAPI key for non-interactive auth (skips login)—
CORELAYER_API_URLServer URLhttps://api.corelayer.com
CORELAYER_AUTH_URLAuth server URL for browser loginhttps://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

  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 summary
  • corelayer integrations list
  • corelayer config get
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> --json

​
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> --json

​
Review integrations for a group

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

​
Summarize current issue health

corelayer issues summary --group <group-id>
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> --json`, and `corelayer integrations list --json`.
- 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: 
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.