Skip to main content
The lobbystack command works with LobbyStack through the API. lobbystack onboard reads one file that describes a business and makes the business match it. It creates the business, adds its knowledge, sets up the agent and services, picks a plan, claims a phone number, and sends the owner a link to take over. When you change the file and run it again, it changes only what differs.

Install the command

The command is part of the LobbyStack repository. You need Node.js 26 and pnpm 10.
The build is one file, packages/cli/dist/bin.js, which runs with Node.js alone. Copy it anywhere, or point an alias at it:

Sign in

lobbystack login checks a key and saves it, with the dashboard’s address, as a profile:
--key-stdin keeps the key out of your shell history. On a self-hosted deployment, use your APP_BASE_URL. lobbystack whoami shows the key in use and its business. Which key you use decides what onboard can do:
  • An API key from Settings > API keys sets up its own business, as long as the business already has the manifest’s name or the manifest gives its ID. Give it business:read, business:write, knowledge:read and knowledge:write, plus billing:manage for a plan, phone_numbers:manage for a number and team:manage to hand the business over, which only a key an owner created can do. See Authentication.
  • A host’s platform key creates new businesses. Whoever runs the deployment makes these keys; see Platform keys. A key with access to every business can also give a business a plan and a number. A key with group access can’t: the owner pays for both, and once they claim the business, the key can’t reach it. Leave plan and phone_number out of its manifest, and the owner picks them in the dashboard. A key with group access also leaves the full read of a website to the owner.
  • A partner’s platform key, from the partner console’s API keys page, creates businesses for the partner. Give it businesses:create, business:read, business:write, knowledge:read, knowledge:write and team:manage, plus phone_numbers:manage and phone_numbers:purchase for a number, which needs a paid tier. With owner in its manifest, the partner invites the owner as it creates the business. Without it, nobody gets an invitation and the business has no owner. business.access_level sets what the business’s own team can use. Leave plan out, because a partner’s businesses don’t buy the host’s plans.
In a script or CI, set LOBBYSTACK_URL and LOBBYSTACK_API_KEY instead of signing in.

Describe the business

Write the business in a YAML or JSON file, such as acme.yaml. Every section but business is optional:
acme.yaml
Put times and phone numbers in quotes. Inside YAML’s { ... } form a comma starts the next field, so write text that has a comma in the indented form, as the FAQ above does.
The command never deletes what the file leaves out. To remove a service, a rule or knowledge, use the dashboard or the other lobbystack commands.

Preview the changes

--plan prints what a run would change, and changes nothing:
A mistake in the file, or a document that’s missing or outside the manifest’s folder, stops the command before it changes anything. The message names where the mistake is, such as services[0].duration_minutes.

Run it

Each line says what a step did:
A checkout and a phone number cost money, so the command asks before it starts either one. Pass --yes to skip the questions, which a script needs: without a terminal to ask in, the command stops instead. To set up a business that already exists, put its ID in business.id. --business <id> works too when the business already has the manifest’s name. The command ignores LOBBYSTACK_BUSINESS and a profile’s saved business, so a new manifest never lands on one by mistake. The claim link goes out once everything else is done, or before the checkout when a key with access to every business sets up a plan the owner pays for. When the owner accepts it, a key with group access and the API key that sent it can’t reach the business any more, and a rerun says so. A key with access to every business still can. A partner’s key never sends a claim link, because the business stays with the partner. It invites an owner the manifest names as it creates the business, and later runs only check that the owner joined or still has the invitation. A partner’s key keeps reaching the business after the owner joins.

When the run waits on someone

Some steps need a person. The command does everything else, prints what it’s waiting for, and exits with code 4:
  • A payment. The command prints the checkout link: send it to whoever pays. Until the plan is paid, the business keeps its current plan. The phone number, documents the free plan has no room for, and the full read of a website wait for the paid plan. A checkout page more than an hour old may have run out: a run in a terminal, without --yes, offers to start a new one.
  • A paid tier. With a partner’s key on Free, the phone number waits until the partner’s owners choose a paid tier.
  • The owner’s claim. With a key that has access to every business, the business’s owner pays for its plan, so the claim link goes out before the checkout. The checkout starts on the first run after the owner accepts the link.
Run the same command again once the person is done. A checkout can buy a plan for a free business, or move Starter to Pro. Other plan changes, such as Pro to Starter or another billing interval, happen in the billing portal: the command reports them and carries on.

Run it again

Run the command again whenever the file changes, or after a run fails. Each step compares the business with the file first and changes only what differs, so a business that already matches gets no changes. The command keeps the IDs it makes in a state file next to the manifest, such as acme.state.json. Keep that file with the manifest:
  • After a failure, the next run picks up where the last one stopped. It sends the same requests again, so it gets back the business, number or checkout it already made instead of a second one.
  • Files are uploaded once. When a file’s contents, title or tags change, the next run uploads the new version and deletes the old one. A file you move within the folder keeps its upload.
  • A document or website that couldn’t be read is read once more on the next run. If it fails the same way again, the command reports it, and lobbystack knowledge retry <id> reads it again once it’s fixed.
  • A state file made against one dashboard is refused against another. Pass --state <path> to keep one per dashboard.
Without a state file, a platform key won’t create a business when you already onboarded one with the same name. Put that business’s ID in business.id to set it up, or give the new business another name. Once its owner claims a business, GET /businesses stops listing it, even for a key with access to every business, so keep the state file, or copy the ID the first run prints into business.id.

Exit codes

--json prints the business ID, the state file, every change and what the run waits on as JSON instead.

Other commands

lobbystack has a command for every API endpoint, grouped like the API: lobbystack services list, lobbystack knowledge upload, lobbystack numbers search, and so on. lobbystack --help lists the groups, and --help after any command lists its options. With a partner’s key, eight more groups run the Partner endpoints: partner, demos, packages, brand, domain, templates, partner-team and payments. For example, lobbystack demos list lists your prospect demos. lobbystack agents list shows the business’s agents. lobbystack receptionist and lobbystack rules change the default agent. lobbystack rules add --channel sms adds a rule for texts only, and lobbystack rules list shows each rule’s channel.

Buy a number for another agent

lobbystack numbers search-extra lists numbers you can buy for another agent, each with its monthly price. Extra numbers need the extra phone numbers add-on, which bills monthly apart from the plan. The first time, run lobbystack billing extra-numbers --wait and send the page it prints to whoever pays. Then buy a number at the price the search showed:
--accept-monthly-price-cents has to match the offer’s price, or the API refuses the purchase. Send null for an offer with no price, as on a self-hosted server. lobbystack numbers list shows each number’s agent and monthly price. --kind toll_free searches toll-free numbers in the US and Canada, which cost $2.15 a month.