Getting started with the Step AI Agent from the CLI
Use the Step CLI to run the AI Agent from your terminal, IDE, or CI/CD job. The AI Agent can work with your existing code base and test assets.
Installation
If you connect to a Step server, use a CLI version matching that server.
You need:
- Java 21 or later (JRE or JDK) for the CLI
- Node.js 24 or newer
- The Step CLI installed and available on your
PATH. - The Step AI Agent itself: download the latest AI Agent package (.jar). Request access if you do not have credentials yet.
- An Anthropic API key scoped to an Anthropic workspace to access Claude.
Export the key in the shell or job that runs it, rather than committing it anywhere:
export ANTHROPIC_API_KEY=sk-ant-...
Quick start
Replace VERSION with the version in your downloaded AI Agent filename, and adjust the example paths to your folders:
step ap execute --local \
--package=/path/to/step-ai-agents-VERSION.jar \
--includePlans="AI Agent - Automate" \
-ep 'apDirectory=/path/to/your-package|instructions={"testCases":[{"name":"wikipedia_black_hole","spec":"Go to https://en.wikipedia.org/wiki/Black_hole and assert the title is Black hole.","mode":"create"}]}'
The two paths do different jobs: --package points to the downloaded AI Agent package (i.e., serves as input), and apDirectory is where the generated Automation Package will be written (i.e., output).
Execution parameters are passed with -ep, separated by |. Quote the whole value with single quotes, so the JSON keeps its double quotes. The command blocks until the run ends and prints the report tree.
To run the AI Agent on a Step instance, omit --local and provide the instance URL and a Step API key:
step ap execute \
--stepUrl=https://your-step-instance \
--token="$STEP_API_KEY" \
--package=/path/to/step-ai-agents-VERSION.jar \
--includePlans="AI Agent - Automate" \
-ep 'apDirectory=/path/to/your-package|instructions={"testCases":[{"name":"wikipedia_black_hole","spec":"Go to https://en.wikipedia.org/wiki/Black_hole and assert the title is Black hole.","mode":"create"}]}'
The Step instance needs a connected Step Node.js agent with Node.js 24 or newer and ANTHROPIC_API_KEY configured as a Step Parameter. See Step instance setup.
See Configuration for every field and parameter, and Agentic test automation from the command line for a worked example end to end.
See Troubleshooting for common execution errors, and Data and privacy for model data handling.