elastic-package CLI
When to use
Use this skill when tasks include:
- validating package structure and formatting
- building a package artifact
- running pipeline or system tests
- managing local Elastic test stack lifecycle
- installing or checking package status in Kibana
When not to use
Do not use this skill as the primary guide for:
- ECS field design decisions (use an ECS-focused skill)
- ingest processor design and parsing strategy (use an ingest-pipeline-focused skill)
- package layout architecture (use a package-structure-focused skill)
Prerequisites
elastic-package is installed and available in PATH- container runtime is available (Docker or Podman)
- you run commands from a package directory (or pass
-C <package-dir>)
Core workflows
1) Validate and build loop
Run this sequence for routine local verification:
elastic-package format
elastic-package lint
elastic-package check
elastic-package build
Notes:
check runs lint and build together and fails fast by default.- use
format --fail-fast when you want read-only verification without rewriting files.
2) Pipeline test loop (fast iteration)
Use Elasticsearch-only stack for quicker feedback:
elastic-package stack up -d --services=elasticsearch
elastic-package test pipeline
elastic-package test pipeline --generate
Then review generated expected files before keeping changes.
3) System test loop (end-to-end)
Use this when you need full ingest behavior with service provisioning:
elastic-package stack up -d
elastic-package service up
elastic-package test system
Use --data-streams <name> to scope tests and reduce run time.
Practical command examples
# format package files
elastic-package format
# lint against package spec and templates
elastic-package lint
# combined validation workflow
elastic-package check
# build package artifact
elastic-package build
# start only Elasticsearch for pipeline tests
elastic-package stack up -d --services=elasticsearch
# run pipeline tests
elastic-package test pipeline
# regenerate expected pipeline outputs
elastic-package test pipeline --generate
# run end-to-end system tests
elastic-package test system
Key flags cheat sheet
- global:
-C, --change-directory, -v, --verbose
- stack:
-d, --daemon, -s, --services, --version, -p, --profile
- pipeline tests:
-d, --data-streams, -g, --generate, -m, --fail-on-missing
- system tests:
--setup, --tear-down, --no-provision, --variant
Quick command map
- validate/build:
format, lint, check, build
- stack lifecycle:
stack up, stack status, stack down
- testing:
test pipeline, test system, test static, test asset, test policy, test script
- package lifecycle:
create, install, status, uninstall
- support:
service up, profiles, benchmark
References
- Failure diagnosis and fixes:
references/troubleshooting.md
1---2name: elastic-package-cli3description: Use when developing or validating Elastic integrations with elastic-package commands such as build, check, lint, format, test, stack, service, install, profiles, and benchmark.4license: Apache-2.05---6
7# elastic-package CLI
8
9
10## When to use
11
12Use this skill when tasks include:
13- validating package structure and formatting
14- building a package artifact
15- running pipeline or system tests
16- managing local Elastic test stack lifecycle
17- installing or checking package status in Kibana
18
19## When not to use
20
21Do not use this skill as the primary guide for:
22- ECS field design decisions (use an ECS-focused skill)
23- ingest processor design and parsing strategy (use an ingest-pipeline-focused skill)
24- package layout architecture (use a package-structure-focused skill)
25
26## Prerequisites
27
28- `elastic-package` is installed and available in `PATH`
29- container runtime is available (Docker or Podman)
30- you run commands from a package directory (or pass `-C <package-dir>`)
31
32## Core workflows
33
34### 1) Validate and build loop
35
36Run this sequence for routine local verification:
37
38```bash
39elastic-package format
40elastic-package lint
41elastic-package check
42elastic-package build
43```
44
45Notes:
46- `check` runs lint and build together and fails fast by default.
47- use `format --fail-fast` when you want read-only verification without rewriting files.
48
49### 2) Pipeline test loop (fast iteration)
50
51Use Elasticsearch-only stack for quicker feedback:
52
53```bash
54elastic-package stack up -d --services=elasticsearch
55elastic-package test pipeline
56elastic-package test pipeline --generate
57```
58
59Then review generated expected files before keeping changes.
60
61### 3) System test loop (end-to-end)
62
63Use this when you need full ingest behavior with service provisioning:
64
65```bash
66elastic-package stack up -d
67elastic-package service up
68elastic-package test system
69```
70
71Use `--data-streams <name>` to scope tests and reduce run time.
72
73## Practical command examples
74
75```bash
76# format package files
77elastic-package format
78
79# lint against package spec and templates
80elastic-package lint
81
82# combined validation workflow
83elastic-package check
84
85# build package artifact
86elastic-package build
87
88# start only Elasticsearch for pipeline tests
89elastic-package stack up -d --services=elasticsearch
90
91# run pipeline tests
92elastic-package test pipeline
93
94# regenerate expected pipeline outputs
95elastic-package test pipeline --generate
96
97# run end-to-end system tests
98elastic-package test system
99```
100
101## Key flags cheat sheet
102
103- global: `-C, --change-directory`, `-v, --verbose`
104- stack: `-d, --daemon`, `-s, --services`, `--version`, `-p, --profile`
105- pipeline tests: `-d, --data-streams`, `-g, --generate`, `-m, --fail-on-missing`
106- system tests: `--setup`, `--tear-down`, `--no-provision`, `--variant`
107
108## Quick command map
109
110- validate/build: `format`, `lint`, `check`, `build`
111- stack lifecycle: `stack up`, `stack status`, `stack down`
112- testing: `test pipeline`, `test system`, `test static`, `test asset`, `test policy`, `test script`
113- package lifecycle: `create`, `install`, `status`, `uninstall`
114- support: `service up`, `profiles`, `benchmark`
115
116## References
117
118- Failure diagnosis and fixes: `references/troubleshooting.md`
119
elastic