| 
 | 1 | +# Annotation CLI  | 
 | 2 | + | 
 | 3 | +A CLI tool for creating and storing annotation properties in Harness CI/CD pipelines, similar to Buildkite's annotate functionality.  | 
 | 4 | + | 
 | 5 | +## Features  | 
 | 6 | + | 
 | 7 | +- **File-based summaries**: Reads markdown content from user-created files  | 
 | 8 | +- **Execution context**: Automatically captures Harness environment variables  | 
 | 9 | +- **Cross-platform**: Compatible with Linux, Mac, and Windows  | 
 | 10 | +- **Multi-step support**: Single annotations.json file for multiple pipeline steps  | 
 | 11 | +- **Append functionality**: Can append additional content to existing steps  | 
 | 12 | + | 
 | 13 | +## Usage  | 
 | 14 | + | 
 | 15 | +```bash  | 
 | 16 | +./cli annotate --context "context-name" --summary "summary-file.md" [options]  | 
 | 17 | +```  | 
 | 18 | + | 
 | 19 | +### Required Parameters  | 
 | 20 | + | 
 | 21 | +- `--context`: Context identifier (used as grouping key)  | 
 | 22 | +- `--summary`: Path to markdown file containing summary content  | 
 | 23 | + | 
 | 24 | +### Optional Parameters  | 
 | 25 | + | 
 | 26 | +- `--style`: Annotation style (replaces existing value)  | 
 | 27 | +- `--priority`: Priority level (default: 5, replaces existing value)  | 
 | 28 | + | 
 | 29 | +### Environment Variables  | 
 | 30 | + | 
 | 31 | +The CLI automatically reads these Harness environment variables:  | 
 | 32 | + | 
 | 33 | +- `HARNESS_EXECUTION_ID`: Current execution ID  | 
 | 34 | +- `HARNESS_STEP_ID`: Current step ID  | 
 | 35 | +- `HARNESS_ACCOUNT_ID`: Account identifier  | 
 | 36 | +- `HARNESS_PROJECT_ID`: Project identifier  | 
 | 37 | +- `HARNESS_ANNOTATIONS_FILE`: If set, target path where the CLI writes annotations JSON  | 
 | 38 | + | 
 | 39 | +## Examples  | 
 | 40 | + | 
 | 41 | +### Basic annotation  | 
 | 42 | +```bash  | 
 | 43 | +./cli annotate --context "build-validation" --summary "test-results.md" --priority 8  | 
 | 44 | +```  | 
 | 45 | + | 
 | 46 | +### Append to existing context (in the same step)  | 
 | 47 | +```bash  | 
 | 48 | +# Reuse the same --context to append additional content within the same step  | 
 | 49 | +./cli annotate --context "build-validation" --summary "additional-notes.md"  | 
 | 50 | +```  | 
 | 51 | + | 
 | 52 | +### With custom style  | 
 | 53 | +```bash  | 
 | 54 | +./cli annotate --context "deployment" --summary "deploy-results.md" --style "success" --priority 9  | 
 | 55 | +```  | 
 | 56 | + | 
 | 57 | +## Output Files  | 
 | 58 | + | 
 | 59 | +- **annotations JSON**: Structured data containing all annotations and metadata. The output path is:  | 
 | 60 | +  1. `HARNESS_ANNOTATIONS_FILE` environment variable (if set)  | 
 | 61 | +  2. `./annotations.json` (default)  | 
 | 62 | +- User-created **.md files**: Summary content files (not modified by CLI)  | 
 | 63 | + | 
 | 64 | +### Notes on Step ID  | 
 | 65 | +- The Harness step identifier is sourced from the environment and stored in `execution_context.harness_step_id`.  | 
 | 66 | +- There is no separate `--stepid` argument; per-step annotations are written to a per-step file (via `HARNESS_ANNOTATIONS_FILE`), and context-based entries are merged within that file.  | 
 | 67 | + | 
 | 68 | +## Build  | 
 | 69 | + | 
 | 70 | +```bash  | 
 | 71 | +go build -o cli main.go  | 
 | 72 | +```  | 
 | 73 | + | 
 | 74 | +For cross-platform builds:  | 
 | 75 | +```bash  | 
 | 76 | +# Linux  | 
 | 77 | +GOOS=linux GOARCH=amd64 go build -o cli-linux main.go  | 
 | 78 | + | 
 | 79 | +# Windows  | 
 | 80 | +GOOS=windows GOARCH=amd64 go build -o cli-windows.exe main.go  | 
 | 81 | + | 
 | 82 | +# macOS  | 
 | 83 | +GOOS=darwin GOARCH=amd64 go build -o cli-macos main.go  | 
0 commit comments