Metadata-Version: 2.4
Name: northcli
Version: 0.1.5
Summary: North Star CLI for spec-driven delivery workflows
Author: North Star
License: Proprietary
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx<1.0.0,>=0.27.0
Requires-Dist: typer<1.0.0,>=0.12.0

# northcli

`northcli` is the local CLI for North Star spec-driven delivery.

## Install

### Option 1 (recommended): pipx

```bash
pipx install northcli
```

### Option 2: user install via pip

```bash
python3 -m pip install --user northcli
```

### Option 3: installer script

macOS/Linux:

```bash
curl -fsSL https://raw.githubusercontent.com/<ORG_OR_USER>/<REPO>/main/scripts/install_northcli.sh | bash
```

Windows PowerShell:

```powershell
iwr https://raw.githubusercontent.com/<ORG_OR_USER>/<REPO>/main/scripts/install_northcli.ps1 -UseBasicParsing | iex
```

For local development installs from this repo, run:

```bash
./scripts/install_northcli.sh "" local
```

## Verify

```bash
northcli --help
northcli login --api-url http://localhost:8000/api/v1
northcli projects
northcli init --project-id 3
northcli ready
northcli pull STORY-123
northcli run STORY-123 --agent codex --copy
northcli done STORY-123 --from-run .northcli/projects/3/runs/STORY-123.result.<timestamp>.json --tool codex
```

`northcli pull` copies the agent prompt (`STORY-123.task.md`) to your clipboard by default.

`northcli run` pulls the story, creates a structured result schema, and (for `--agent codex`)
executes `codex exec` with:
- `--output-schema <schema file>`
- `-o <run output json>`

It still supports clipboard handoff via `--copy`.

`northcli done` supports structured run output via `--from-run` and can still parse
legacy report text (`--report-file`) and auto-attach git metadata (`--auto-git`).

If you need to re-copy later:

```bash
northcli copy-prompt STORY-123
```

## Config layout

- Global auth config: `~/.config/northcli/config.toml`
- Local project config: `.northcli/config.toml`
- Local story packs: `.northcli/projects/<project_id>/stories/`

## Maintainer release flow

1. Bump version in `pyproject.toml`.
2. Push a git tag `northcli-vX.Y.Z`.
3. GitHub Action `Release northcli` builds and publishes to PyPI.

Use PyPI Trusted Publishing with repository environment `pypi`.

Detailed runbook: `../docs/northcli_release_runbook.md`.
