crowbot/cli

Standalone Crow CLI for reading events, listening for handoffs, and fetching implementation plans.

Maintainers

Package info

github.com/danrichards/crow-cli

Type:project

pkg:composer/crowbot/cli

Transparency log

Statistics

Installs: 2

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

Security

Advisories: 0

Aikido package health analysis

dev-master 2026-07-07 21:07 UTC

Requires

Requires (Dev)

MIT 92ec4f5773384d121d4b290a62cfed34d5cb936b

Published on Packagist.org on 2026-07-07 21:08 UTC

This package is auto-updated.

Last update: 2026-07-07 21:08:34 UTC

README

Crow CLI is a standalone command-line companion for Crow developer handoffs. It reads queued Crow events, listens for live forwarded events, and fetches implementation-plan handoffs in formats that are ready to paste into an AI coding agent or use directly in a terminal workflow.

The app is built with Laravel Zero and ships as a PHAR-backed crow executable.

Installation

Once the package is published, install it globally with Composer:

composer global require crowbot/cli

Make sure Composer's global bin directory is on your PATH, then verify the install:

crow list

For local development from this repository:

composer install
php crow list

The checked-in PHAR build is available at:

./builds/crow list

Authentication

Run the login command:

crow auth login

The CLI prints the API-token page URL, attempts to open it in your browser, then prompts for the token. If your terminal supports clickable links, you can also open the printed URL directly.

Credentials are stored at:

<project>/.crow/config.json

When you run crow auth login from inside a project, the CLI writes credentials to that project's .crow/config.json. This lets different projects use different Crow accounts and API tokens. If no project root can be detected, credentials fall back to the global config at ~/.crow/config.json.

Use --global when you intentionally want shared credentials:

crow auth login --global

Config files are written with restrictive permissions where the platform supports it. Environment variables remain supported for automation and CI.

Configuration precedence is:

  1. Explicit command options, such as --api-token or --api-url
  2. Environment variables
  3. The nearest project config discovered by walking upward from the current directory: .crow/config.json
  4. Global config: ~/.crow/config.json
  5. Built-in defaults

Supported environment variables:

CROW_API_URL=https://crow.test/api/v1
CROW_API_TOKEN=your_token_here
CROW_APP_ID=
CROW_LISTEN_PUBLIC_URL=
CROW_LISTEN_HOST=127.0.0.1
CROW_LISTEN_PORT=8787
CROW_LISTEN_SECRET=

The current default API URL is https://crow.test/api/v1.

For automation or headless environments, pass the token and skip browser launch:

crow auth login --api-token=your_token_here --no-browser

To point one command at a specific config file, set CROW_CONFIG_PATH:

CROW_CONFIG_PATH=/path/to/.crow/config.json crow plan

Commands

Fetch Implementation Plans

List active implementation plans:

crow plan

Fetch a specific plan handoff:

crow plan <plan-id>

Print raw JSON:

crow plan <plan-id> --json

Write output to a file:

crow plan <plan-id> --output=handoff.md

Read Crow Events

Read the latest unread event:

crow read

Read a specific event:

crow read <event-id>

Leave the event unread after printing:

crow read <event-id> --leave-unread

Filter unread lookup by app or event types:

crow read --app-id=123 --events=dispatch.received --events=recon.ready

Listen For Live Events

Start a local listener:

crow listen --public-url=https://your-public-url.example

The listener binds to 127.0.0.1:8787 by default and receives events at:

POST /crow/events
GET /health

Override the bind address:

crow listen --host=127.0.0.1 --port=8787

Start the listener without registering it with Crow:

crow listen --no-register

When registering with Crow, expose the local listener first and set CROW_LISTEN_PUBLIC_URL or pass --public-url.

Compatibility Aliases

The old Artisan-style command names are still available as aliases:

crow crow:plan
crow crow:read
crow crow:listen

The preferred CLI interface is:

crow plan
crow read
crow listen

Development

Install dependencies:

composer install

Run the test suite:

composer test

Inspect available commands:

php crow list

Build the PHAR:

php crow app:build crow --build-version=unreleased

Smoke-test the built artifact:

./builds/crow plan --help

Release Notes

This repository is now the standalone Crow CLI. It is no longer a Laravel installable package that auto-registers Artisan commands inside a host application.

For Packagist distribution, composer.json points its bin entry at builds/crow, so release builds should include a fresh PHAR artifact.