Ranch.Bot CLI Setup

Read livestock records from your terminal with the public @ranchbot/cli 1.0.0 package. You need Node.js 22 or newer, an internet connection, and a Ranch.Bot account with access to a farm. For everyday record entry, start with SMS and web setup.

Install

Version and help work without signing in. To run without a global installation:

For any command below, you can replace ranchbot with npx -y @ranchbot/cli@1.0.0.

Sign in and select a farm

Open the URL printed by login in your browser, sign in, and approve the displayed code. Login uses OAuth. You do not need an API key or a token pasted into an assistant. Select a farm ID from the list, then replace <farm_id> below:

Check that the account and selected farm are correct before reading records. To select a farm for one command without changing the saved default:

Command help and JSON output

Place command flags after the leaf command, as shown above. Use --json for scripts and agents. A successful command exits with code 0 and writes its result to stdout. A failure exits non-zero and writes an error envelope to stderr. Check the exit code before parsing output or reporting success.

The CLI includes animals, identifiers, groups, records, chute sessions, rations, feedings, and read-only Farm Memory. Use the installed version's help for its exact command surface. Do not assume newer source-only commands are included in 1.0.0.

Use with a shell-capable assistant

An assistant permitted to execute local shell commands can use this CLI after you sign in. Give it the public agent skill, confirm the farm, and start with a read such as ranchbot animals list --json. This describes shell use, not a verified integration with an individual assistant client.

CLI writes execute directly under your server permissions. They do not pause at the Ranch.Bot app confirmation screen or create the Action rows behind its Change History. Review the operation, farm, targets, and values before allowing an assistant to create, change, or delete data. The CLI does not enforce an assistant's approval procedure. The app and SMS review-before-saving workflow has different controls.

The MCP package and Registry listing remain unpublished. Ranch.Bot operates no hosted MCP endpoint; ChatGPT web and Gemini have no hosted Ranch.Bot connection.

Sign out and upgrade

Ordinary sessions refresh automatically. Logout revokes the refresh session and removes local credentials. If authentication fails, run ranchbot login again. Never print or share credential files under ~/.ranchbot/. The selected farm is saved separately from credentials; check it after signing in again.

Stop all older CLI and MCP processes before upgrading. Concurrent old and new locking protocols are unsupported. Do not delete or replace lock files while clients are running; a lock file's presence does not mean a process holds the lock. Read release notes, install the intended version, then check version, help, identity, and farm selection again.

Specialized capabilities

The observer profile is for read-only SMS-to-record inspection. It is restricted to the user's active SMS farm and inspection routes, not a general read-only farm-data profile. Sessions expire after one hour. Including message content deliberately exposes private data to the assistant session.

Admin imports use a separate OAuth client and require server-authorized admin access. Ordinary login does not grant import administration. Customers upload files through the supervised import workflow.

See the CLI reference for these specialized commands and release notes for the published version. For help, email support@ranch.bot.