cli.mdx

title	CLI Reference
description	Everything to do with the CLI

It all starts with calling

$ agentstack

Shortcut Aliases

Many top-level AgentStack commands can be invoked using a single-letter prefix to save keystrokes. These are indicated in the command's documentation here after a | character. Run agentstack help for the full list.

Global Flags

These flags work with all commands:

--debug - Print a full traceback when an error is encountered. This also enables printing additional debug information from within AgentStack useful for development and debugging.

--path=<path> - Set the working directory of the current AgentStack project. By default agentstack works inside of the current directory and looks for an agentstack.json file there. By passing a path to this flag you can work on a project from outside of it's directory.

--version - Prints the current version and exits.

$ agentstack init

This initializes a new AgentStack project.

agentstack init <slug_name>

slug_name is the name of your project, and will be created as a directory to initialize your project inside. When the default arguments are passed, a starter project template will be used, which adds a single agent, a single task and demonstrates the use of a tool.

Init Creates a Virtual Environment

AgentStack creates a new directory, initializes a new virtual environment, installs dependencies, and populates the project structure. After init completes, cd into the directory, activate the virtual environment with source .venv/bin/activate. Virtual environments and package management are handled by the uv package manager.

Initializing with the Wizard

You can pass the --wizard flag to agentstack init to use an interactive project configuration wizard.

Initializing from a Template

You can also pass a --template=<template_name> argument to agentstack init which will pre-populate your project with functionality from a built-in template, or one found on the internet. A template_name can be one of three identifiers:

• A built-in AgentStack template (see the templates/proj_templates directory in the AgentStack repo for bundled templates).
• A template file from the internet; pass the full https URL of the template.
• A local template file; pass an absolute or relative path.

$ agentstack run

This runs your AgentStack project.

agentstack run

Environment variables will be loaded from ~/.env and from the .env file inside your project directory. Make sure you have enabled your project's venv before executing to include all dependencies required.

Overriding Inputs

Your project defines Inputs which are used to customize the Agent and Task prompts for a specific task. In cases where using the inputs.yaml file to populate data is not flexible enough, run can accept value overrides for all defined inputs. Use --input-<input_key>=<input_value> to pass data which will only be used on this run.

For example, if you have a key in your inputs.yaml file named topic and want to override it for this run, you would use the following command:

agentstack run --input-topic=Sports

Running other project commands

By default, run will call the main() function inside your project's main.py file. You can pass alternate function names to run with --function=<function_name>.

Generate

Code generation commands for automatically creating new agents or tasks.

$ agentstack generate agent | agentstack g a

Generate a new agent

• agent_name (required | str) - the name of the agent
• --role (optional | str) - Prompt parameter: The role of the agent
• --goal (optional | str) - Prompt parameter: The goal of the agent
• --backstory (optional | str) - Prompt parameter: The backstory of the agent
• --llm (optional | <provider>/<model>) - Which model to use for this agent

Default LLM

All arguments to generate a new Agent are optional. A default LLM can be configured in agentstack.jsonunder the default_model setting to populate a provider/model. If you are generating an agent in a project which does not have a default model set, you will be prompted to configure one.

Example

agentstack generate agent script_writer

$ agentstack generate task | agentstack g t

Generate a new task

• task_name (required | str) - the name of the task
• --description (optional | str) - Prompt parameter: Explain the task in detail
• --expected_output (optional | str) - What is the expected output from the agent (ex: data in json format)
• --agent (optional | str) - The name of the agent of which to assign the task to (when using Crew in sequential mode)

Example

agentstack g t gen_script --description "Write a short film script about secret agents"

Tools

Tools are what make AgentStack powerful. Adding and removing Tools from Agents is easy with this command.

$ agentstack tools list | agentstack t l

Lists all tools available in AgentStack.

$ agentstack tools add | agentstack t a

Shows an interactive interface for selecting which Tool to add and which Agents to add it to.

Add a Tool to all Agents

When a tool_name is provided it will be made available to all Agents in the project.

$ agentstack tools add <tool_name>

Add a Tool to a single Agent

When an agent_name is provided, the tool will be made available to only that agent.

$ agentstack tools add <tool_name> --agent=<agent_name>

Add a Tool to multiple Agents

When a comma-separated list of Agents is passed, the tool will be made available to those agents.

$ agentstack tools add <tool_name> --agents=<agent_name>,<agent_name>,<agent_name>

$ agentstack tools remove <tool_name>

Removes a tool from all Agents in the project.

Templates

Projects can be exported into a template to facilitate sharing configurations. Re-initialize a project from a template with agentstack init --template=<filename>.

$ agentstack export <filename>

The current project will be written to a JSON template at the provided filename.

$ agentstack update

Check for updates and allow the user to install the latest release of AgentStack.

$ agentstack login

Authenticate with agentstack.sh for hosted integrations.