CLI

The nextfarm command brings the NextFarm AI farm assistant and the developer platform to your terminal: type nextfarm to chat on your farm's real data, plus subcommands to call the API, manage API keys, receive webhooks locally and set up MCP for other assistants.

Install

macOS / Linux

curl -fsSL https://developers.nextfarm.vn/install.sh | sh

Windows (PowerShell)

irm https://developers.nextfarm.vn/install.ps1 | iex

Homebrew

brew install nextx-organization/nextfarm/nextfarm

npm (Node ≥ 20)

npm install -g nextfarm

Available for macOS (Apple Silicon and Intel), Linux (x64, arm64) and Windows x64. Source and releases: nextfarm-cli · version 0.3.3

Quickstart

Shell

nextfarm login            # browser; over SSH use --qr and scan with the NextFarm app
nextfarm                  # open the chat
nextfarm -p "which plots are due for harvest this week" --json
nextfarm doctor

The assistant writes only after you confirm. Anything that touches devices, automation or money (pumps, valves, rules that run on their own, cash entries) is confirmed in the NextFarm app only; the server also refuses it from the terminal.
Scripts and CI: set NEXTFARM_API_KEY and use nextfarm tools call, nextfarm api. Chatting with the assistant needs a user login.
The Free plan has 30 AI questions a week for the whole farm, reset at 00:00 Monday (Vietnam time). Run nextfarm ai usage to check.

Login

Method	Use when
`nextfarm login`	A machine with a browser — OAuth + PKCE, the session renews itself.
`nextfarm login --qr`	Over SSH: scan the QR code with the NextFarm app.
`nextfarm login --device`	No browser and no app: enter the device code at id.nextfarm.vn/oauth/device on another device.
`NEXTFARM_API_KEY`	Scripts, servers, read-only CI — limited to the API key's scopes, no AI chat.
`nextfarm login --ci`	GitHub Actions / GitLab CI: exchange the OIDC token for a 15-minute session, no secret in the repository. Register the repo with ci trust add.

Permission mode

Mode	Meaning
`read`	Read only — the assistant proposes no writes.
`propose`	Default: the assistant creates write proposals and you confirm each one (y/N).
`auto`	Writes routine changes on its own; large writes still need the number typed back.

Devices, automation and money (pumps, valves, irrigation schedules, cash entries) are confirmed in the NextFarm app only, in every mode — the server refuses them from the terminal.

Slash commands

Command	What it does
`/help`	Commands and shortcuts
`/new`	New conversation (keeps workspace, agent)
`/resume [query]`	Resume an earlier conversation
`/rename <name>`	Rename this conversation
`/pin`	Pin / unpin this conversation
`/workspace [code]`	Switch workspace
`/mode read\|propose\|auto`	Permission mode: read · propose · auto
`/model [name]`	Switch model: NextFarm AI or your own
`/attach <file>`	Attach an Excel / CSV / image / text file
`/undo [id]`	Undo the last write
`/why [runId]`	Why the AI answered that way (steps, tools)
`/memory`	What the AI remembers — edit, lock, forget
`/schedule "question" daily 08:00`	Schedule a question daily / weekly / monthly
`/sau-benh <photo>`	Diagnose pests and diseases from a photo
`/thoi-tiet [plot]`	Weather for the farm or a plot in the coming days
`/ban-tin`	The farm's latest morning brief
`/export md\|json [file]`	Export the conversation to Markdown / JSON
`/tools`	AI tools you can use (by your real permissions)
`/usage`	AI questions left this week
`/feedback up\|down`	Rate the last answer
`/status`	Account, workspace, environment, version
`/doctor`	Check connectivity, clock, token, plan
`/config [key value]`	Settings: language, color, update notices
`/init`	Create NEXTFARM.md: instructions for this folder
`/mcp`	Install the MCP server into another client
`/logout`	Log out this profile
`/clear`	Clear the screen (keeps the conversation)
`/exit`	Exit

Keys	What it does
`Enter · Shift+Enter (\ + Enter)`	Send · new line
`/`	Command menu
`@`	Attach a file, pick an Agent for this message
`#`	Quick note into this folder's NEXTFARM.md
`Shift+Tab`	Cycle permission mode
`Esc`	Stop the running answer
`Esc Esc`	Edit the last message
`↑ / ↓`	Input history
`Ctrl+O`	Expand / collapse steps
`Ctrl+L`	Clear screen
`Ctrl+C · Ctrl+D`	Clear input (twice to exit) · exit

Command reference

Command	What it does
`nextfarm login`	log in (browser or QR, chosen automatically)
`nextfarm logout`	log out this profile (revokes the server session)
`nextfarm status`	account, workspace, environment, AI plan, session
`nextfarm sessions`	your login sessions on all devices
`nextfarm sessions list`	list sessions
`nextfarm sessions revoke`	revoke one session, or --others for all other sessions
`nextfarm workspace`	your workspaces (companies)
`nextfarm workspace list`	list workspaces
`nextfarm workspace use`	switch the working workspace (saved in the profile)
`nextfarm ai`	AI assistant: ask, history, proposals, memory, schedules
`nextfarm ai ask`	ask one question non-interactively (same as -p)
`nextfarm ai history`	list conversations
`nextfarm ai show`	print a whole conversation
`nextfarm ai rename`	rename a conversation (empty = clear)
`nextfarm ai pin`	pin a conversation
`nextfarm ai delete`	delete a conversation permanently
`nextfarm ai why`	why the assistant answered that way: steps and tools
`nextfarm ai apply`	approve a proposed write (real write)
`nextfarm ai reject`	reject a proposed write
`nextfarm ai undo`	undo a written proposal (within 24 hours)
`nextfarm ai memory`	what the assistant remembers about the farm
`nextfarm ai memory list`
`nextfarm ai memory forget`	forget one item (farm owner only)
`nextfarm ai schedule`	recurring questions
`nextfarm ai schedule list`
`nextfarm ai schedule add`
`nextfarm ai schedule run`
`nextfarm ai schedule delete`
`nextfarm ai brief`	latest morning brief
`nextfarm ai pest`	diagnose pests and diseases from a photo
`nextfarm ai usage`	AI questions left this week
`nextfarm ai feedback`	rate an answer: up / down
`nextfarm model`	your own models for --model (keys stay in the keychain, never sent to NextFarm)
`nextfarm model list`	models you added
`nextfarm model add`	add a provider: claude, gemini, gpt, grok, ollama
`nextfarm model remove`	remove a model and delete its key
`nextfarm model default`	model used by default (nextfarm = NextFarm AI)
`nextfarm tools`	AI tools you can use (by your real permissions)
`nextfarm tools login`	grant AI tool access to the CLI on this machine (once)
`nextfarm tools logout`	revoke the CLI's AI tool access
`nextfarm tools list`	list tools
`nextfarm tools describe`	parameters and an example for a tool
`nextfarm tools call`	call a tool. Write tools only create a proposal to confirm
`nextfarm api`	call the API directly (e.g. api GET /gis/parcels -f page_size=5)
`nextfarm keys`	workspace API keys
`nextfarm keys list`	list keys
`nextfarm keys create`	create a key (printed once)
`nextfarm keys revoke`	revoke a key (stops immediately)
`nextfarm keys delete`	delete a key
`nextfarm keys usage`	calls over 7 days
`nextfarm keys calls`	last 50 calls of a key
`nextfarm webhooks`	webhook events: browse, trigger, listen locally
`nextfarm webhooks events`	list events
`nextfarm webhooks schema`	payload schema and example
`nextfarm webhooks endpoints`	your webhook endpoints
`nextfarm webhooks endpoints list`
`nextfarm webhooks endpoints create`
`nextfarm webhooks endpoints delete`
`nextfarm webhooks endpoints rotate-secret`	rotate the signing secret (old one stays valid for a while)
`nextfarm webhooks trigger`	send a sample event to an endpoint
`nextfarm webhooks deliveries`	recent deliveries
`nextfarm webhooks retry`	retry a delivery
`nextfarm webhooks verify`	verify a webhook signature locally (no server call)
`nextfarm webhooks listen`	receive real events on this machine and forward them locally
`nextfarm openapi`	download the public OpenAPI spec
`nextfarm openapi pull`
`nextfarm docs`	open the docs (cli, quickstart, api-keys, oauth, mcp, ai-tools, webhooks, sdk, errors, rate-limit, sandbox, changelog, versioning, security)
`nextfarm changelog`	recent API changes
`nextfarm mcp`	connect the MCP server to other AI assistants
`nextfarm mcp url`	print the MCP server URL
`nextfarm mcp install`	install into: chatgpt, claude, claude-desktop, codex, copilot, cursor, gemini, grok, vscode, windsurf
`nextfarm mcp uninstall`
`nextfarm mcp serve`	serve MCP over stdio with the CLI's grant (for clients without OAuth)
`nextfarm ci`	secretless CI login (OIDC)
`nextfarm ci trust`	CI repositories allowed to log in to this workspace
`nextfarm ci trust list`
`nextfarm ci trust add`	allow a repository to log in (tokens act as you, live 15 minutes)
`nextfarm ci trust revoke`	revoke (immediate)
`nextfarm ci policy`	pre-approval policies: let CI write within a ceiling
`nextfarm ci policy list`
`nextfarm ci policy kinds`	kinds a policy can cover
`nextfarm ci policy show`
`nextfarm ci policy request`	ask to let a CI repository write (an API-key manager approves; with that permission it is active at once)
`nextfarm ci policy revoke`	revoke (the next write goes back to a link)
`nextfarm ci example`	print a sample GitHub Actions workflow
`nextfarm doctor`	check connectivity, clock, token, plan, version
`nextfarm config`	settings
`nextfarm config list`
`nextfarm config get`
`nextfarm config set`	lang · mode · updateChannel · updateCheck · telemetry · color · defaultProfile
`nextfarm completion`	Tab completion for bash \| zsh \| fish \| powershell
`nextfarm update`	upgrade to the latest version
`nextfarm init`	create NEXTFARM.md: instructions for this folder

`nextfarm login`

Flag	Meaning
`--web`	log in with the browser
`--qr`	scan with the NextFarm app (SSH, headless machines)
`--device`	enter a code on another device (RFC 8628)
`--ci`	in GitHub Actions/GitLab CI: exchange the OIDC token for a short-lived token
`--no-browser`	do not open the browser, print the link only

`nextfarm logout`

log out this profile (revokes the server session)

Flag	Meaning
`--all`	log out every profile on this machine

`nextfarm sessions revoke [id]`

revoke one session, or --others for all other sessions

Flag	Meaning
`--others`	every session except this one

`nextfarm workspace use [code]`

switch the working workspace (saved in the profile)

`nextfarm ai ask <question...>`

ask one question non-interactively (same as -p)

Flag	Meaning
`--conversation <id>`	continue this conversation

`nextfarm ai history`

list conversations

Flag	Meaning
`--search <text>`	filter by text
`--limit <n>`	rows · default 30

`nextfarm ai show <id>`

print a whole conversation

`nextfarm ai rename <id> [title...]`

rename a conversation (empty = clear)

`nextfarm ai pin <id>`

pin a conversation

Flag	Meaning
`--off`	unpin

`nextfarm ai delete <id>`

delete a conversation permanently

`nextfarm ai why [runId]`

why the assistant answered that way: steps and tools

`nextfarm ai apply <proposalId>`

approve a proposed write (real write)

`nextfarm ai reject <proposalId>`

reject a proposed write

`nextfarm ai undo <proposalId>`

undo a written proposal (within 24 hours)

`nextfarm ai memory forget <id>`

forget one item (farm owner only)

`nextfarm ai schedule add <question>`

Flag	Meaning
`--at <HH:mm>`	time (Vietnam time)
`--weekday <1-7>`	one weekday only (1 = Monday); omit = daily

`nextfarm ai schedule run <id>`

`nextfarm ai schedule delete <id>`

`nextfarm ai pest <photo> [note...]`

diagnose pests and diseases from a photo

`nextfarm ai feedback <runId> <vote>`

rate an answer: up / down

`nextfarm model add <provider>`

add a provider: claude, gemini, gpt, grok, ollama

Flag	Meaning
`--key-from-stdin`	read the API key from stdin (never put keys on the command line)
`--name <model>`	model used when only the provider is given
`--url <url>`	server address (Ollama or a compatible endpoint)

`nextfarm model remove <name>`

remove a model and delete its key

`nextfarm model default <name>`

model used by default (nextfarm = NextFarm AI)

Flag	Meaning
`--no-browser`	do not open the browser

`nextfarm tools list`

list tools

Flag	Meaning
`--module <m>`	filter by module (gis, iot, office…)
`--kind <k>`	filter by kind (read \| proposal \| export)
`--public`	public catalog (no login)

`nextfarm tools describe <name>`

parameters and an example for a tool

`nextfarm tools call <name>`

call a tool. Write tools only create a proposal to confirm

Flag	Meaning
`--args <json>`	JSON arguments
`--args-file <file>`	arguments from a JSON file (- = stdin)
`-a, --arg <key=value>`	one argument (repeatable)

`nextfarm api <method> <path>`

call the API directly (e.g. api GET /gis/parcels -f page_size=5)

Flag	Meaning
`-f, --raw-field <key=value>`	string parameter: query for GET/DELETE, JSON body for POST/PUT/PATCH (repeatable)
`-F, --field <key=value>`	like -f but typed: numbers, true/false, JSON
`--input <file>`	request body from a JSON file (- = stdin)
`-H, --header <K: V>`	extra header (repeatable)
`--paginate`	follow all pages (items/pageNumber results)
`--select <path>`	print only part of the result, e.g. .items[0].name
`-i, --include`	print status and headers too
`--idempotency-key <key>`	idempotency key for POST

`nextfarm keys create`

create a key (printed once)

Flag	Meaning
`--name <name>`
`--scopes <codes>`	permission codes, comma separated, e.g. gis.parcels.view,iot.devices.view
`--expires <dur>`	lifetime: 30d, 6m, 1y · default 90d
`--description <text>`

`nextfarm keys revoke <id>`

revoke a key (stops immediately)

`nextfarm keys delete <id>`

delete a key

`nextfarm keys usage [id]`

calls over 7 days

`nextfarm keys calls <id>`

last 50 calls of a key

`nextfarm webhooks events`

list events

Flag	Meaning
`--module <m>`

`nextfarm webhooks schema <event>`

payload schema and example

`nextfarm webhooks endpoints create <url>`

Flag	Meaning
`--events <list>`	events, comma separated
`--description <text>`

`nextfarm webhooks endpoints delete <id>`

`nextfarm webhooks endpoints rotate-secret <id>`

rotate the signing secret (old one stays valid for a while)

`nextfarm webhooks trigger <event>`

send a sample event to an endpoint

Flag	Meaning
`--endpoint <id>`	target endpoint (default: first one subscribed)

`nextfarm webhooks deliveries`

recent deliveries

Flag	Meaning
`--status <s>`	success \| failed \| pending
`--endpoint <id>`
`--limit <n>`	· default 30

`nextfarm webhooks retry <deliveryId>`

retry a delivery

`nextfarm webhooks verify`

verify a webhook signature locally (no server call)

Flag	Meaning
`--secret <secret>`
`--payload <file>`	raw received body (- = stdin)
`-H, --header <K: V>`	received header (repeatable)
`--signature <sig>`	signature from the *-Signature-256 header
`--timestamp <ts>`	timestamp from the *-Timestamp header

`nextfarm webhooks listen`

receive real events on this machine and forward them locally

Flag	Meaning
`--forward-to <url>`	e.g. localhost:3000/hook
`--events <list>`	events, comma separated (default: all)
`--print-secret`	print the full signing secret
`--print-json`	print event bodies

`nextfarm openapi pull`

Flag	Meaning
`--module <m>`	one module only
`-o, --out <file>`	· default openapi.json

`nextfarm docs [topic]`

open the docs (cli, quickstart, api-keys, oauth, mcp, ai-tools, webhooks, sdk, errors, rate-limit, sandbox, changelog, versioning, security)

`nextfarm mcp install [clients...]`

install into: chatgpt, claude, claude-desktop, codex, copilot, cursor, gemini, grok, vscode, windsurf

`nextfarm mcp uninstall <client>`

`nextfarm mcp serve`

serve MCP over stdio with the CLI's grant (for clients without OAuth)

Flag	Meaning
`--stdio`	use stdin/stdout (default)

`nextfarm ci trust add`

allow a repository to log in (tokens act as you, live 15 minutes)

Flag	Meaning
`--repo <owner/repo>`
`--provider <p>`	github \| gitlab · default github
`--ref <ref>`	branch or tag prefix, e.g. main · refs/tags/v* · default main
`--environment <name>`	required GitHub environment (recommended for the main branch)
`--expires <dur>`	lifetime: 90d, 1y
`--name <name>`

`nextfarm ci trust revoke <id>`

revoke (immediate)

`nextfarm ci policy show <id>`

`nextfarm ci policy request`

ask to let a CI repository write (an API-key manager approves; with that permission it is active at once)

Flag	Meaning
`--trust <id\|owner/repo>`	CI trust (see: ci trust list)
`--kinds <a,b>`	kinds (see: ci policy kinds)
`--max <n>`	record ceiling (1–1000) · default 50
`--expires <dur>`	lifetime, at most 30d · default 14d
`--note <text>`
`--approve`	approve now (needs API-key manage permission)

`nextfarm ci policy revoke <id>`

revoke (the next write goes back to a link)

`nextfarm ci example`

print a sample GitHub Actions workflow

Flag	Meaning
`--repo <owner/repo>`
`--workspace <code>`
`--write`	sample that writes (needs a policy: ci policy request)

`nextfarm config get <key>`

`nextfarm config set <key> <value>`

lang · mode · updateChannel · updateCheck · telemetry · color · defaultProfile

`nextfarm completion <shell>`

Tab completion for bash | zsh | fish | powershell

`nextfarm update`

upgrade to the latest version

Flag	Meaning
`--channel <c>`	latest \| next

Scripting & CI

Shell

nextfarm -p "summarise this week's log" --json   # non-interactive, prints JSON
nextfarm tools call parcels_list --args '{"page_size":5}'
nextfarm api GET /gis/parcels -f page_size=5

In CI a nextfarm login --ci session has nobody to confirm: a write proposal is written only under a pre-approval policy for that repository (kinds, record limit, at most 30 days) — see nextfarm ci policy. Otherwise the command prints a link to confirm in the app and exits with code 7.

Global flags

Flag	Meaning
`-v, --version`	print the version
`-p, --print [question]`	non-interactive: print the answer and exit (reads stdin too)
`-c, --continue`	continue the last conversation
`-r, --resume [id]`	resume a conversation (no id = pick from a list)
`-f, --file <path>`	attach an Excel/CSV, image or text file (repeatable, max 3)
`--profile <name>`	login profile
`--sandbox`	use the sandbox environment
`-w, --workspace <code>`	run this command on another workspace
`--agent <code>`	choose an Agent instead of the general assistant
`--model <provider/name>`	use your own model over MCP: claude, gemini, gpt, grok, ollama/<name>
`--mode <mode>`	permission mode
`--output-format <format>`	output format
`--json`	shorthand for --output-format json
`--lang <lang>`	language
`--no-color`	disable colors
`--quiet`	print results only
`--verbose`	verbose output
`--debug`	print request ids and timings (never tokens)

Environment variables

NEXTFARM_API_KEY · NEXTFARM_TOKEN · NEXTFARM_PROFILE · NEXTFARM_ENV · NEXTFARM_WORKSPACE · NEXTFARM_LANG · NEXTFARM_DEBUG · NEXTFARM_NO_UPDATE_CHECK · NEXTFARM_NO_KEYCHAIN · NEXTFARM_ID_TOKEN

Exit codes

Exit code	Meaning
`0`	Success
`1`	General or server error
`2`	Invalid usage
`3`	Not logged in or session expired
`4`	Missing permission, scope or plan
`5`	AI quota used up or rate limited
`6`	Network error
`7`	Write proposal not confirmed
`8`	Not found
`130`	Interrupted (Ctrl+C)

CLI

Install

Quickstart

Login

Permission mode

Slash commands

Command reference

nextfarm login

nextfarm logout

nextfarm sessions revoke [id]

nextfarm workspace use [code]

nextfarm ai ask <question...>

nextfarm ai history

nextfarm ai show <id>

nextfarm ai rename <id> [title...]

nextfarm ai pin <id>

nextfarm ai delete <id>

nextfarm ai why [runId]

nextfarm ai apply <proposalId>

nextfarm ai reject <proposalId>

nextfarm ai undo <proposalId>

nextfarm ai memory forget <id>

nextfarm ai schedule add <question>

nextfarm ai schedule run <id>

nextfarm ai schedule delete <id>

nextfarm ai pest <photo> [note...]

nextfarm ai feedback <runId> <vote>

nextfarm model add <provider>

nextfarm model remove <name>

nextfarm model default <name>

nextfarm tools login

nextfarm tools list

nextfarm tools describe <name>

nextfarm tools call <name>

nextfarm api <method> <path>

nextfarm keys create

nextfarm keys revoke <id>

nextfarm keys delete <id>

nextfarm keys usage [id]

nextfarm keys calls <id>

nextfarm webhooks events

nextfarm webhooks schema <event>

nextfarm webhooks endpoints create <url>

nextfarm webhooks endpoints delete <id>

nextfarm webhooks endpoints rotate-secret <id>

nextfarm webhooks trigger <event>

nextfarm webhooks deliveries

nextfarm webhooks retry <deliveryId>

nextfarm webhooks verify

nextfarm webhooks listen

nextfarm openapi pull

nextfarm docs [topic]

nextfarm mcp install [clients...]

nextfarm mcp uninstall <client>

nextfarm mcp serve

nextfarm ci trust add

nextfarm ci trust revoke <id>

nextfarm ci policy show <id>

nextfarm ci policy request

nextfarm ci policy revoke <id>

nextfarm ci example

nextfarm config get <key>

nextfarm config set <key> <value>

nextfarm completion <shell>

nextfarm update