Merge pull request #202 from tcdent/docs-catchup

Update CLI docs to reflect current command state and `uv` integration

Author: bboynton97

docs/cli-reference/cli.mdx

@@ -8,57 +8,150 @@ It all starts with calling
 $ agentstack
 ```
 
-## `$ init | i`
+### 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
 agentstack init <slug_name>
 ```
 
-- `slug_name` (optional | str) - the name of your project
-- `--no-wizard` (boolean flag) - skips the wizard step and applies default values to project init
+`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. 
 
-## `$ generate | g`
+### 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.
+```bash
+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
+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.
 
-### `agent | a`
+### `$ 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
 
-### `task | t`
+#### 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
+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)
 
-### Examples
+#### Example
+```bash Generate Task
+agentstack g t gen_script --description "Write a short film script about secret agents"
+```
 
-<CodeGroup>
-```bash Generate Agent
-agentstack generate agent script_writer
+## 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
+$ agentstack tools add <tool_name>
 ```
 
-```bash Generate Task
-agentstack g t gen_script --description Write a short film script about secret agents
+#### Add a Tool to a single Agent
+When an agent_name is provided, the tool will be made available to only that agent. 
+```bash
+$ agentstack tools add <tool_name> --agent=<agent_name>
 ```
-</CodeGroup>
 
+#### 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
+$ agentstack tools add <tool_name> --agents=<agent_name>,<agent_name>,<agent_name>
+```
 
-## `$ tools | t`
-Tools are what make AgentStack powerful. Adding tools is easy with this command.
+### `$ agentstack tools remove <tool_name>`
+Removes a tool from all Agents in the project. 
 
-### `list | l`
-Lists all tools available in AgentStack.
 
-### `add | a`
-Add a tool by name. By default, this command adds all tools from the provider to every agent.
-- `name` (required | str) - The name of the tool to add
+## 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. 
 
-### Examples
-```bash
-agentstack tools add browserbase
-```