BearPass Command Line Interface (CLI)

Важно

Доступно только для платных тарифов

Интерфейс командной строки BearPass (CLI) — это инструмент, который позволяет вам работать с паролями и папками напрямую из терминала: получать данные, создавать, изменять и удалять элементы, а также переносить данные из Стандартного пространства в Защищённое. Данная CLI-утилита упрощает работу с паролями в автоматизациях и скриптах, и особенно полезна для DevOps-инженеров.

CLI поддерживает два способа аутентификации: через API-ключ и через JWT-токен от внешнего OIDC-провайдера. Подробнее о настройке доверенных провайдеров и создании JWT-привязок — в разделе «Аутентификация с использованием JWT-токенов внешних провайдеров».

Узнать о всех возможностях CLI-клиента можно с помощью аргумента --help

shell

Bearpass CLI client

Usage: bearpass <command> [args]

Available commands:
   config     Configure main settings
   create     Create a password or a folder
   delete     Move passwords or folders to the trash
   get        Get password data
   migrate    Move the items of a regular space into an encrypted space
   update     Update a password or a folder

Run: bearpass <command> help

Скачивание и установка

Для amd64:

shell

wget https://services.bearpass.ru/downloads/bearpass-amd64.zip
unzip bearpass-amd64.zip
chmod +x bearpass

Для arm64:

shell

wget https://services.bearpass.ru/downloads/bearpass-arm64.zip
unzip bearpass-arm64.zip
chmod +x bearpass

Начало работы

Перед началом работы с CLI-клиентом его необходимо сконфигурировать.

Это можно сделать с помощью:

Переменных окружения
Запуска команды config

Переменные окружения

Установите переменные окружения

BEARPASS_API_URL - URL сервера BearPass в формате https://bearpass.company.com/
BEARPASS_AUTH_TYPE - способ аутентификации: api_key или jwt
BEARPASS_API_KEY - Ключ API пользователя, через которого будет производиться работа с CLI клиентом
BEARPASS_JWT_TOKEN - JWT-токен от внешнего OIDC-провайдера (передаётся в BearPass для аутентификации)
BEARPASS_MASTER_PASSWORD — мастер-пароль для доступа к Защищённым корпоративным пространствам и персональному пространству.

Переменные окружения имеют приоритет над файлом конфигурации.

Запуск команды config

Для интерактивной настройки запустите команду ./bearpass config

Процесс конфигурации:

Введите URL сервера BearPass (например, https://bearpass.company.com/).
Выберите метод аутентификации:

Введите jwt для использования JWT-токена
Нажмите Enter для выбора API-ключа (значение по умолчанию)

Введите учётные данные:

Для API-ключа: введите ключ
Для JWT: вставьте JWT-токен от внешнего провайдера

Те же параметры можно передать флагами, без интерактивного режима:

shell

./bearpass config --url=https://bearpass.company.com/ --auth=api_key --api-key=<key>
./bearpass config --url=https://bearpass.company.com/ --auth=jwt --jwt=<token>

Данные будут сохранены в файл ~/.bearpass/config

WARNING

При использовании JWT-токена CLI не проверяет его на этапе конфигурации. Проверка произойдёт при первом запросе к API.

Доступные команды

get

Получение данных пароля по id

shell

./bearpass get --help

Usage: bearpass get <id> [args]

<id> - Password id as number

Available arguments:
  --field=<string>   Specify the field to get from BearPass password. Available fields: name, space_id, parent_id, type, comment, quality_percent, actual_percent, compromised_count, archived, personal, favorite, created_at, version, url, login. For additional fields use syntax: additional_field[field name]. Example: --field=additional_field[port]

Special fields:
  password  - decrypted password value

Для получения всех данных пароля необходимо запустить команду в формате bearpass get <id>, например: bearpass get 1.

Стандартный формат ответа — json.

Для получения данных отдельного поля необходимо указать флаг --field=<fieldName>
Все доступные поля: name, space_id, parent_id, type, comment, quality_percent, actual_percent, compromised_count, archived, personal, favorite, created_at, version, url, login, password
Для получения данных дополнительного поля необходимо указать additional_field и название поля в кавычках, например --field="additional_field[ip address]"

Пароли из Защищённых пространств и персонального пространства расшифровываются на стороне клиента. Для этого в CLI должен быть задан мастер-пароль.

Примеры:

shell

./bearpass get 2 --field=password
9!2%P0jw^Ns38gW

shell

./bearpass get 2 --field="additional_field[ip address]"
8.8.8.8

create

Создание пароля или папки

shell

./bearpass create --help

Usage: bearpass create --name=<name> [args]

Creates a password (default) or a folder. A password requires --parent-id.

Available arguments:
  --additional-field=[<type>:]<name>=<value>   Additional field, may be repeated. Type is one of input, text, password, totp and defaults to input
  --comment=<string>                           Note of the item
  --login=<string>                             Login of the password
  --name=<string>                              Name of the item
  --parent-id=<number>                         Id of the parent folder
  --password=<string>                          Password value. Use --password=- to be prompted for it instead, keeping it out of the shell history; piped or redirected input is read to the end
  --personal                                   Create the item in the personal container
  --space-id=<number>                          Id of the space to create the item in
  --tag=<string>                               Tag of the item, may be repeated
  --type=password|folder                       Type of the item, password by default
  --url=<string>                               URL of the password

По умолчанию создаётся пароль, для создания папки укажите --type=folder. Для пароля обязательно укажите папку, в которую он будет помещён, — флаг --parent-id. У папки нельзя задать логин, пароль, URL и дополнительные поля.

Пространство задаётся флагом --space-id, персональное пространство — флагом --personal. Если не указан ни один из них, элемент создаётся в системном пространстве (ID=1).

Чтобы пароль не попал в историю командной строки, укажите --password=-: CLI запросит пароль в терминале или прочитает его из перенаправленного ввода.

Дополнительное поле задаётся в формате --additional-field=[<тип>:]<название>=<значение>. Доступные типы: input (по умолчанию), text, password, totp. Флаги --additional-field и --tag можно указывать несколько раз.

В ответ CLI выводит в формате json данные созданного элемента, в том числе его id.

Примеры:

shell

./bearpass create --name="Team folder" --type=folder --space-id=3

shell

./bearpass create --name="My server" --parent-id=12 --login=root --password=- \
  --additional-field="ip address=10.0.0.5" --additional-field=password:root-db=s3cret --tag=prod < secret.txt

update

Изменение пароля или папки по id

shell

./bearpass update <id> [args]

Команда меняет только те поля, которые указаны в аргументах, остальные остаются без изменений. Аргументы те же, что у create, кроме --type, --space-id и --personal: тип элемента и пространство изменить нельзя. Флаг --parent-id перемещает элемент в другую папку.

Особенности:

--tag и --additional-field заменяют весь список тегов или дополнительных полей элемента. Чтобы удалить все теги или все дополнительные поля, используйте флаги --no-tags и --no-additional-fields.
Если пароль не меняется, CLI считывает его текущее значение, чтобы сохранить его. В журнале элемента такое чтение отображается как просмотр пароля.

Примеры:

shell

./bearpass update 42 --name="New name"
./bearpass update 42 --password=- < secret.txt
./bearpass update 42 --tag=prod --tag=db

delete

Перемещение паролей и папок в корзину по id

shell

./bearpass delete <id> [<id>...]

Можно указать один или несколько id через пробел. Папка удаляется вместе со всем содержимым. Удалённые элементы можно восстановить из корзины в веб-интерфейсе.

shell

./bearpass delete 42 43 44

config

Конфигурация CLI клиента

Для работы с Защищёнными корпоративными пространствами или персональным пространством CLI-клиенту требуется знать мастер-пароль, чтобы расшифровывать данные на стороне клиента. Добавьте флаг --master-password после выполнения команды конфигурации:

shell

bearpass config --master-password=<password>

Мастер-пароль нужен только для чтения зашифрованных данных. Для создания и изменения элементов в Защищённых пространствах он не требуется.

Перенос данных из Стандартного пространства в Защищённое

Команда migrate копирует папки и пароли из Стандартного пространства в Защищённое с сохранением структуры папок и прав доступа.

shell

./bearpass migrate --from-space=<id> --to-space=<id> [args]

Аргумент	Описание
`--from-space`	ID Стандартного пространства, из которого переносятся данные
`--to-space`	ID Защищённого пространства, в которое переносятся данные
`--mode`	Режим переноса прав: `strict` (по умолчанию), `partial` или `items`
`--state`	Файл состояния переноса, по умолчанию `migrate-<from>-<to>.state.jsonl` в текущей папке
`--log`	Журнал переноса, по умолчанию `migrate-<from>-<to>.log.jsonl` в текущей папке
`--rate`	Ограничение числа запросов в минуту, по умолчанию 240

Перенос — разовая операция, а не синхронизация. Исходное пространство остаётся без изменений: после проверки результата вы сами решаете, удалить его или ограничить к нему доступ.

Требования

Запускайте перенос от пользователя с ролью «Администратор». Если для переноса используется отдельная роль, ей нужны все права из списка:

«Доступ ко всем паролям и папкам» для исходного пространства;
«Управление пространствами» или «Управление выбранными пространствами» с выбранными исходным и целевым пространствами;
«Управление всеми группами» — для чтения состава групп, которым выданы права;
«Использование API».

Кроме того, пользователь должен быть участником обоих пространств и иметь заданный мастер-пароль. Вводить мастер-пароль в CLI для переноса не нужно.

Подготовка

До запуска добавьте в целевое пространство всех, у кого есть доступ к элементам исходного пространства, и выдайте им ключи. Ключ нельзя выдать пользователю, у которого не задан мастер-пароль: попросите таких пользователей заранее войти в BearPass и задать его.

Учтите особенности:

Права заблокированных пользователей CLI не видит и не переносит. Разблокируйте временно заблокированных пользователей до переноса или выдайте им доступ вручную после разблокировки.
Пользователь, запустивший перенос, получает право «Администрирование» на каждый созданный элемент. Если перенос запускался не от администратора, снимите эти права после переноса.
Не вносите изменения в исходное пространство на время переноса и проверки результата.

Режимы переноса прав

Режим	Что делает
`strict`	Сначала проверяет права всех элементов. Если кому-то нельзя выдать доступ в целевом пространстве, ничего не переносит и записывает проблемы в журнал.
`partial`	Переносит элементы сразу. Права, которые нельзя перенести, пропускаются и записываются в журнал.
`items`	Переносит элементы без прав. Доступ к ним получат только пользователь, запустивший перенос, и администраторы.

Рекомендуемый порядок: запустите перенос в режиме strict, исправьте проблемы из журнала и запустите ту же команду снова. Режим partial подходит, если потеря части доступов осознанно принята.

Что переносится

Переносится	Не переносится
Папки и их вложенность	Вложенные файлы
Название, логин, пароль, URL, заметка, теги, иконка	История версий
Дополнительные поля	Журнал элемента
Архивный статус	Избранное других пользователей
Права доступа пользователей и групп, включая срок действия	Ссылки на пароли
	Политики паролей
	Элементы из корзины

Элементы с вложенными файлами переносятся без файлов и отмечаются в журнале, файлы к ним нужно добавить вручную. Срок действия права переносится датой, время устанавливается на 23:59:59.

Перенос оставляет следы в журналах:

каждое чтение пароля записывается в журнал исходного элемента как просмотр пароля от имени пользователя, запустившего перенос. Если на такие события настроены правила безопасности, предупредите о переносе ответственных за них;
качество пароля пересчитывается на стороне клиента, поэтому оно может немного отличаться от исходного.

Прерывание и повторный запуск

Прогресс сохраняется в файл состояния после каждого элемента. Если перенос прервался, запустите ту же команду из той же папки: перенос продолжится без создания дублей. Не удаляйте файл состояния до завершения работы — без него повторный запуск создаст все элементы заново.

Повторный запуск переносит только новые элементы. Изменения и удаления элементов в исходном пространстве после их переноса не учитываются.

Результат переноса

Итог переноса выводится в формате json. Подробности записываются в журнал, по одному событию в строке.

Основные поля итога:

migrated / already_migrated — перенесено при этом запуске / при предыдущих запусках;
blocking_issues — число пользователей и групп, из-за которых перенос в режиме strict не начался;
permissions_set / permissions_skipped / permissions_failed — права перенесены / пропущены / не перенесены из-за ошибки;
items_with_files_not_migrated — элементы, файлы которых нужно перенести вручную;
archived — элементы, перенесённые в архив.

Причины, по которым право не перенесено (поле reason в журнале):

reason	Что значит	Что сделать
`not_in_target_space`	Пользователь не состоит в целевом пространстве	Добавить пользователя и выдать ключ
`no_space_key`	Пользователю не выдан ключ пространства	Выдать ключ
`no_public_key`	У пользователя не задан мастер-пароль	Попросить задать мастер-пароль, затем выдать ключ
`group_members_unknown`	Нет права читать состав группы	Выдать право «Управление всеми группами»

Коды выхода: 0 — всё перенесено; 1 — перенос заблокирован, прерван или завершился с ошибками (см. журнал); 2 — ошибка в аргументах.

Особенности работы с JWT-аутентификацией

Обновление последнего использования: При каждом успешном запросе (например, bearpass get) в веб-интерфейсе на вкладке JWT-авторизация обновляется дата в колонке «Последнее использование» для соответствующей привязки.

Зависимость от провайдера: Если доверенный провайдер деактивирован или удалён, CLI будет получать ошибку аутентификации. При повторной активации провайдера доступ восстанавливается автоматически.

BearPass Command Line Interface (CLI) ​

Скачивание и установка ​

Начало работы ​

Переменные окружения ​

Запуск команды config ​

Доступные команды ​

get ​

create ​

update ​

delete ​

config ​

Перенос данных из Стандартного пространства в Защищённое ​

Требования ​

Подготовка ​

Режимы переноса прав ​

Что переносится ​

Прерывание и повторный запуск ​

Результат переноса ​

Особенности работы с JWT-аутентификацией ​

BearPass Command Line Interface (CLI)

Скачивание и установка

Начало работы

Переменные окружения

Запуск команды config

Доступные команды

get

create

update

delete

config

Перенос данных из Стандартного пространства в Защищённое

Требования

Подготовка

Режимы переноса прав

Что переносится

Прерывание и повторный запуск

Результат переноса

Особенности работы с JWT-аутентификацией