.. _setup_local_dev:

Local Development Setup
==========================

This guide explains how to develop and test bots locally using VSCode and the Ugly Bot CLI, instead of using the web editor.

Prerequisites
--------------

- Python 3.10 or later
- `VSCode <https://code.visualstudio.com/>`_ (optional, for the extension)

Set Up Project
---------------

Create a directory for your bot and set up a virtual environment:

.. code-block:: bash

   mkdir my-bot && cd my-bot
   python -m venv venv
   source venv/bin/activate      # macOS/Linux
   venv\Scripts\activate          # Windows

Install the Ugly Bot CLI and SDK into the virtual environment:

.. code-block:: bash

   pip install ugly-bot

Verify the installation:

.. code-block:: bash

   ugly-bot --help

To upgrade to the latest version:

.. code-block:: bash

   pip install --upgrade ugly-bot

.. note::

   Always activate your virtual environment before running ``ugly-bot`` commands. The CLI, dev tunnel, and your bot code all run from the same venv.

Login
------

Authenticate the CLI with your Ugly Bot account:

.. code-block:: bash

   ugly-bot login

This opens your browser to log in. After logging in, the CLI stores a token locally at ``~/.ugly-bot/auth.json``.

Sync Bot Code
--------------

Download an existing bot's code to your local machine:

.. code-block:: bash

   ugly-bot sync <botId>

This creates the bot's files in the current directory and generates an ``ugly-bot.json`` config file.

To find your ``botId``, open the bot's **Settings** tab and look under the **Local Development** section — click **Copy Bot ID** to copy it to your clipboard.

To re-sync later (e.g., after someone edits via the web editor):

.. code-block:: bash

   ugly-bot sync

This uses the ``botId`` from ``ugly-bot.json``.

If your bot has additional dependencies, install them:

.. code-block:: bash

   pip install -r requirements.txt

Start Dev Tunnel
-----------------

Run the dev tunnel to route your bot's traffic to your local machine:

.. code-block:: bash

   ugly-bot dev

This:

#. Connects to the Ugly Bot server via WebSocket
#. Registers a tunnel for your bot
#. Watches for ``.py`` file changes and hot-reloads automatically
#. Routes only **your** messages to the local bot — other users' traffic is unaffected

While the tunnel is active, open a conversation with your bot on the website. Your messages will trigger the local code instead of the production code.

Make Changes
-------------

Edit your bot's Python files in any editor. When you save a ``.py`` file, the dev tunnel automatically kills the running bot process. The next message triggers a fresh process with your updated code.

Publish
--------

When you're ready to deploy your changes to production:

.. code-block:: bash

   ugly-bot publish

This uploads all local files (respecting ``.gitignore``) to the server's bot code database. Other users will immediately see the updated bot.

VSCode Extension
-----------------

For a streamlined experience, install the Ugly Bot VSCode extension.

Installing the Extension
^^^^^^^^^^^^^^^^^^^^^^^^^^

#. Download ``ugly-bot.vsix`` from the bot's **Settings** tab (under "Local Development")
#. In VSCode, open the Command Palette (``Ctrl+Shift+P`` / ``Cmd+Shift+P``)
#. Run **Extensions: Install from VSIX...**
#. Select the downloaded ``.vsix`` file

Using the Extension
^^^^^^^^^^^^^^^^^^^^^

The extension activates when your workspace contains an ``ugly-bot.json`` file.

**Status Bar**: Shows tunnel status in the bottom bar. Click to start the dev tunnel.

**Commands** (via Command Palette):

- **Ugly Bot: Start Dev Tunnel** — starts ``ugly-bot dev`` in the integrated terminal
- **Ugly Bot: Stop Dev Tunnel** — stops the tunnel
- **Ugly Bot: Sync Bot Code** — runs ``ugly-bot sync``
- **Ugly Bot: Publish Bot Code** — runs ``ugly-bot publish``
- **Ugly Bot: Open Preview** — opens an embedded browser panel showing the Ugly Bot website

Typical Workflow
-----------------

#. Create project directory and virtual environment
#. ``pip install ugly-bot`` — install CLI and SDK
#. ``ugly-bot login`` — authenticate
#. ``ugly-bot sync <botId>`` — download bot code
#. ``pip install -r requirements.txt`` — install bot dependencies
#. ``ugly-bot dev`` — start the dev tunnel
#. Edit code, test in browser, iterate
#. ``ugly-bot publish`` — deploy to production