CLI

Команда looma выпускает сервис на Looma Float из терминала: от исходников до prod и карточки в каталоге. Код сервиса вызывает модели через SDK, ИИ-агент работает через MCP-сервер.

В CLI, API и манифесте сервис называется app: флаг --app, команда looma apps, адреса /v1/apps. В остальном тексте это сервис.

Установка

Нужен Python 3.10 или новее, других зависимостей нет.

uv tool install "git+https://github.com/LoomaFloat/looma-kit"
looma --version

Можно и через pipx: pipx install "git+https://github.com/LoomaFloat/looma-kit". Из клона репозитория: uv tool install .. Обновление: uv tool install --reinstall "git+https://github.com/LoomaFloat/looma-kit".

Полный список команд: looma --help, флаги команды: looma <команда> --help.

Путь автора

looma login                 # подтвердите вход в кабинете автора, ключ сохранится сам
looma init my-bot           # заготовка: looma.yaml и app.py
cd my-bot
looma dev                   # у себя: http://127.0.0.1:8080, база и бакет в Docker
looma deploy                # собрать релиз, он встанет на staging
looma open --env staging    # https://my-bot-staging.apps.loomafloat.ru/
looma promote               # staging → prod: https://my-bot.apps.loomafloat.ru/
looma publish               # карточка из listing с ценами из events уходит на модерацию

Сервис берётся из --app, иначе по имени из looma.yaml текущей папки.

Вход

Команда	Что делает
`looma login`	вход через браузер: код в терминале, подтверждение в кабинете автора на странице `console.loomafloat.ru/device`. Страница показывает, с какой машины и с какого адреса запрошен вход. Ключ выпускается и сохраняется сам
`looma login --no-browser`	браузер не открывается сам: `looma login` печатает ссылку и код, ссылку откройте сами
`looma login --key <ключ>`	вход готовым ключом, для CI и серверов без браузера
`looma login --paste`	вставить готовый ключ вручную: `looma login` спросит его и не покажет на экране
`looma logout`	забыть сохранённый ключ
`looma whoami`	кто вошёл: почта, проект, права ключа, адрес API

Код подтверждения действует 10 минут. Ключ выпускается в проекте того, кто подтвердил вход, с именем «looma CLI · <машина>». Готовый ключ для --key и --paste выпускается в кабинете автора, в разделе «Подключение» (console.loomafloat.ru/connect).

Ключ хранится в ~/.config/looma/config.json с правами 0600, только для владельца. Если задан XDG_CONFIG_HOME, файл лежит в $XDG_CONFIG_HOME/looma/config.json.

Переменные окружения сильнее файла:

Переменная	Что
`LOOMA_API_KEY`	ключ проекта (`looma_sk_…`), например в CI
`LOOMA_API_URL`	адрес API
`LOOMA_CONFIG`	другой файл настроек

Адрес API для одной команды задаёт общий флаг --api: looma --api <адрес> status.

ИИ-агенту ключ отдельно не нужен: CLI и MCP-сервер берут его из looma login.

Проект

Команда	Что делает
`looma init [папка] [-t шаблон] [--name имя]`	заготовка сервиса из шаблона. По умолчанию шаблон `hello`, папка называется по шаблону, имя сервиса берётся из имени папки
`looma sdk [папка]`	свежая копия SDK в папке `loomafloat/` проекта, после обновления looma-kit; заменяет только модули SDK
`looma assess [папка] [--json] [--out файл]`	оценка проекта для переноса: подойдёт ли площадке, что мешает, что переделать (с местом `файл:строка`), черновик `looma.yaml`. Ключ не нужен. `--out` сохраняет отчёт в Markdown
`looma validate [папка]`	проверка `looma.yaml` и проекта без релиза: все ошибки манифеста сразу, модели из `gpu` против каталога, иконка, Dockerfile, архив. Без входа манифест проверяется только локально
`looma models`	модели каталога: имя для `gpu`, тип, отвечает или спит, контекст

Поля манифеста описаны в справке looma.yaml.

Выпуск и окружения

У сервиса два окружения. На staging встаёт каждый новый релиз, на prod релиз попадает только переводом.

Команда	Что делает
`looma deploy [папка] [--promote] [--no-wait]`	упаковать проект, собрать релиз и поставить на staging, с `--promote` сразу и на prod. Если сборка не удалась, покажет хвост лога сборки. С `--no-wait` не ждёт сборки: итог покажет `looma releases`
`looma check [--env staging] [--path /] [--public]`	запрос к веб-процессу сервиса: код ответа, время, начало ответа. По умолчанию идёт через API владельца и доходит до процесса и при `access: clients`. С `--public` идёт по публичному адресу, как гость. Спящий веб-процесс просыпается от этого запроса, до двух минут
`looma status`	окружения, адреса, процессы, сертификат
`looma logs [процесс] [--env prod] [--tail 200] [-f]`	лог процесса, по умолчанию web на prod; `-f` следит за новыми строками
`looma releases`	релизы: номер, статус, время, ошибка
`looma promote [--release N]`	перевести на prod релиз со staging или названный
`looma rollback [--env prod]`	вернуть окружение на прошлый релиз
`looma stop [--env]`	остановить окружение, без `--env` оба. Запустить снова: `looma promote` или `looma deploy`
`looma restart процесс [--env prod]`	перезапустить процесс, он подхватит новые секреты; задачу cron запустить сейчас
`looma open [--env prod] [--print-only]`	открыть адрес сервиса; с `--print-only` только напечатать его
`looma apps`	ваши сервисы: релизы на staging и prod, адрес
`looma destroy --yes`	удалить сервис с релизами, данными (база и бакет) и карточкой. Это необратимо

В релиз не попадают .git, node_modules, виртуальные окружения, кэши, .env и то, что перечислено в .loomaignore. Если код импортирует loomafloat, а копии SDK в проекте нет, looma deploy положит её сам.

Секреты

Команда	Что делает
`looma secrets`	имена секретов и время изменения; значения не показываются
`looma secrets set ИМЯ=значение …`	поставить секреты процессов
`looma secrets unset ИМЯ …`	убрать секреты

Процессы видят новые значения после перезапуска: looma restart процесс.

Статистика и каталог

Команда	Что делает
`looma stats [--days 30]`	статистика сервиса за `--days` дней, не больше 90: запросы по каналам, клиенты, события, вызовы моделей, себестоимость по прайсу моделей
`looma publish`	отправить карточку на модерацию: раздел `listing` и цены из `events` берутся из `looma.yaml` релиза на prod
`looma listing`	состояние карточки: в каталоге ли, что на модерации, причина отказа
`looma unpublish`	снять карточку с каталога; вернуть её: `looma publish`, снова через модерацию

Цены событий задаются в events манифеста, в рублях. Доход и себестоимость моделей по всем сервисам видны в кабинете автора, в разделе «Доход». Выплат пока нет: раздел показывает учёт. Подробно: Клиенты и цены, Публикация и модерация.

ИИ-агенты

Команда	Что делает
`looma skill install [--agent claude\|cursor\|codex\|copilot\|gemini\|agents] [--project [папка]]`	skills `looma-port` и `looma-apps` туда, где их читает агент. По умолчанию для Claude Code в домашний каталог, с `--project` в проект. `--agent` можно повторить
`looma skill path`	где лежат skills
`looma mcp`	MCP-сервер с инструментами `looma_*` для ИИ-агента автора
`looma mcp --print-config`	готовые настройки MCP для популярных агентов
`looma mcp --install-skill`	skills для Claude Code, то же, что `looma skill install`

Как подключить сервер и что умеют инструменты: MCP-сервер.

Запуск у себя: `looma dev`

looma dev                 # процессы здесь, база и бакет в Docker; Ctrl+C останавливает
looma dev --docker        # процессы в образе, собранном как на площадке
looma dev run nightly     # процесс один раз (cron вне расписания)
eval "$(looma dev env)"   # переменные процесса в свой терминал или IDE
looma dev down [--wipe]   # остановить базу и бакет; --wipe удаляет их с данными

Ещё флаги: --only web,worker запускает только названные процессы, --no-data запускает без базы и бакета и без Docker, --dir указывает папку с looma.yaml.

Процесс получает то же, что на площадке: PORT, DATABASE_URL и PG*, AWS_* и LOOMA_BUCKET, LOOMA_APP_TOKEN и LOOMA_API_URL. LOOMA_ENVIRONMENT равен dev.

Модели настоящие, через dev-токен сервиса: только объявленные в gpu, не больше 200 вызовов в сутки на сервис и свой предел в минуту, поэтому отладка не задевает работающий сервис. Манифест проверяет сервер, ошибки те же, что у looma deploy.
База: Postgres с pgvector. Бакет: SeaweedFS (S3). Образы те же, что на площадке. Контейнеры называются looma-dev-<имя>-postgres и looma-dev-<имя>-s3, порты открыты только на 127.0.0.1, данные лежат в томах Docker и переживают перезапуск.
Секреты берутся из файла .env в папке проекта, в релиз он не попадает. Значения с площадки сюда не приходят. Ваш LOOMA_API_KEY и свои AWS_* процесс не видит, как и на площадке.
Без --docker процессы идут на вашей машине, зависимости ставьте сами (pip install -r requirements.txt). Сервис с runtime: docker всегда идёт в образе.
Если сервиса на площадке ещё нет, looma dev заведёт его: только имя, без релизов.

Шаблоны `looma init -t …`

Шаблон	Что внутри
`hello`	страница, которая знает своё окружение и релиз
`assistant`	чат на большой модели: ответ печатается по мере генерации, характер задаёт секрет `ASSISTANT_SYSTEM`; инструмент MCP `ask`
`image-studio`	генерация и правка изображений, галерея в бакете сервиса (у каждого клиента своя), инструмент MCP `draw`
`video-studio`	ролик на 5 секунд по описанию: задание считает площадка, готовый ролик лежит в бакете, событие `video`

Шаблонам с моделями looma init кладёт в проект копию SDK (loomafloat/), поэтому сборка на площадке не ходит за ним в PyPI. Обновить копию после обновления looma-kit: looma sdk. Модели указаны в gpu манифеста. Чтобы взять другую модель, поменяйте её там и в коде или секретом, как написано в README шаблона.

CLI