# Quick start for developers (CLI)

This guide will show you how to create and deploy a new agent using the `th` command line interface.

## Initial setup

First, install the Toolhouse CLI:

```
npm i -g @toolhouseai/cli
```

The CLI will need a Toolhouse API key. Type `th login` to automatically get one. This command will open your default browser and ask you to log into Toolhouse or create a new account, if you haven't done so already.

**Note:** you will only need to run this command once.

```bash
th login
```

Your API Key will be stored in the `~/.toolhouse` file.

{% hint style="info" %}
**Other ways to login**

As an alternative you can pass an API Key by doing one of these actions:

* Manually create a `~/.toolhouse` file and add `TOOLHOUSE_API_KEY=(your API Key)`
* Set a `TOOLHOUSE_API_KEY` environment variable with your API Key.
  {% endhint %}

## Step 0: Create your th file

You can now create a Toolhouse agent file, or **th file** for short. A th file is a YAML file containing the setup for your agent. Type `th new` to create a new agent file:

```bash
th new hello.yaml
```

The CLI will create a `hello.yaml` file in your current folder.

## Step 1: Test your agent

You can test your agent by running it via `th run`.

```bash
th run hello.yaml
```

Running the agent will show the configuration parameters and will stream any MCP server calls and the final output. You can change the th file and run `th run` again to see new results.

Once you're happy with the results, you can deploy your agent.

## Step 2: Deploy your agent

You can deploy your agent by typing `th deploy`. You agent will be deployed as an API with its own unique URL:

```bash
th deploy hello.yaml
```

You will receive a URL similar to this:

```
https://agents.toolhouse.ai/a1d93c2e-7013-4cea-b857-a27980a52ba2
```

You can simply call your agent as an HTTP `POST` request, and it will stream the response using the configuration from your th file.

{% tabs %}
{% tab title="cURL" %}

```bash
curl -XPOST https://agents.toolhouse.ai/a1d93c2e-7013-4cea-b857-a27980a52ba2
```

{% endtab %}

{% tab title="fetch" %}

```javascript
// Remember to run npm i fetch-event-stream
import { events, stream } from 'fetch-event-stream';

const agent = 'https://agents.toolhouse.ai/a1d93c2e-7013-4cea-b857-a27980a52ba2';

const abort = new AbortController();
const response = await fetch(agent, { method: 'POST' });

if (response.ok) {
  const stream = events(res, abort.signal);
  for await (let event of stream) {
    process.stdout.write(event.data);
  }
}
```

{% endtab %}

{% tab title="httpx" %}

```python
import httpx
import asyncio

agent_url = 'https://agents.toolhouse.ai/a1d93c2e-7013-4cea-b857-a27980a52ba2'

async def main():
    async with httpx.AsyncClient() as client:
        async with client.stream('POST', agent_url) as response:
            if response.status_code == 200:
                async for chunk in response.aiter_bytes():
                    print(chunk.decode(), end='')

asyncio.run(main())
```

{% endtab %}

{% tab title="requests" %}

```python
import requests

agent = 'https://agents.toolhouse.ai/a1d93c2e-7013-4cea-b857-a27980a52ba2'

response = requests.post(agent, stream=True)
response.raise_for_status()

for chunk in response.iter_content(decode_unicode=True):
    print(chunk, end='', flush=True)
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Agents are public on the Free plan**

Free plan users can only create public agents.

Pro users can set the visibility of their agents to Private before deploying.

[**Learn more**](https://docs.toolhouse.ai/toolhouse/advanced-concepts/build-agents-with-the-th-file#public)
{% endhint %}