> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentstack.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> Everything to do with the CLI

It all starts with calling

```bash theme={null}
$ 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.

```bash theme={null}
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` 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.

```bash theme={null}
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:

```bash theme={null}
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.json`under 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

```bash Generate Agent theme={null}
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

```bash Generate Task theme={null}
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.

```bash theme={null}
$ 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.

```bash theme={null}
$ 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.

```bash theme={null}
$ 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](https://agentstack.sh) for hosted integrations.