Lantfly CLI

lantfly is the command line for Lantfly. It talks to the Lantfly API (/api/v3): log in, scaffold an actor, push it, run it, and read runs, datasets and key-value stores. It is the @lantfly/cli package (version 0.2.1).

Install

Coming soon to npm

@lantfly/cli is not published to the npm registry yet. Once it is, install it with the commands below.

npm

Terminal

npm install --global @lantfly/cli
lantfly --help

yarn

Terminal

yarn global add @lantfly/cli
lantfly --help

pnpm

Terminal

pnpm add --global @lantfly/cli
lantfly --help

npx

Terminal

npx @lantfly/cli --help

You need Node.js 20 or newer. lantfly --version (or -v) prints the version.

Log in

1. Create an API token in the Console under Settings → API & integrations (see API tokens).

2. Log in with the Lantfly URL and the token:

   Terminal

   lantfly login --url https://lantfly.com --token "$LANTFLY_TOKEN"

   Without the flags, login asks for the URL and the token. Always enter https://lantfly.com as the URL: the CLI's built-in default is a local development server.

3. Check who you are:

   Terminal

   lantfly info

login checks the token with GET /api/v3/me and saves it in ~/.lantfly/auth.json, readable only by you (mode 0600). lantfly logout removes the file.

Override the login for one command

Flags win over environment variables, which win over the saved login:

Flag	Environment variable	Meaning
--url <origin>	LANTFLY_URL	Lantfly server, for example https://lantfly.com. /api/v3 is added.
--token <token>	LANTFLY_TOKEN	API token.
--account <id>	LANTFLY_ACCOUNT	Organization id, or personal.
	LANTFLY_CONFIG_DIR	Folder of auth.json (default ~/.lantfly).

In CI, set LANTFLY_URL and LANTFLY_TOKEN and skip login.

Organizations

Terminal

lantfly accounts use 42          # act for organization 42 (X-Lantfly-Account: 42)
lantfly accounts use personal    # back to your personal account

You can also log in with a token created for the organization.

Global flags

Every command takes these flags, before or after the command name:

Flag	Meaning
--json	Print the API's JSON on stdout (lists as { data, meta }). Logs and progress go to stderr.
--url <origin>	Lantfly server origin.
--token <token>	API token.
--account <id>	Organization id for X-Lantfly-Account, or personal.
-v, --version	Print the CLI version (root only).
-h, --help	Help for any command.

Commands

lantfly login, logout, info

Command	What it does
lantfly login	Log in with an API token (verified with GET /api/v3/me).
lantfly logout	Forget the stored token.
lantfly info	Show the API URL, user id, username, name, email, acting account and plan.
lantfly accounts use <account>	Act for an organization id, or personal.

lantfly init <name>

Scaffolds a Node.js actor in a new folder <name>:

Terminal

lantfly init my-actor
cd my-actor
npm install && npm start    # runs locally, writes ./storage

It creates package.json (depends on @lantfly/actor-sdk), src/main.js, a Dockerfile, .dockerignore, .gitignore, README.md, .actor/actor.json, .actor/input_schema.json, .actor/dataset_schema.json and a sample input in storage/key_value_stores/default/INPUT.json. See Quickstart.

lantfly push

Creates or updates the actor from .actor/actor.json, creates or updates its version, and gets the image built.

Terminal

lantfly push                                  # upload the folder and build it
lantfly push --version 0.2                    # another version than actor.json says
lantfly push --git-url https://github.com/you/my-actor --git-ref main
lantfly push --build                          # build from the folder's Git origin remote
lantfly push --no-upload                      # print docker commands instead
lantfly push --image-tag 2026-11-01           # point the version at an image tag you pushed

Flag	Meaning
--version <x.y>	Actor version (default: version in actor.json).
--image <image>	Image without tag (default: image in actor.json, the actor's current image, or lantfly/<namespace>/<name>).
--image-tag <tag>	Point the version at this image tag. Never uploads.
--git-url <url>	Build from this public HTTPS Git repository.
--git-ref <ref>	Branch, tag or commit to build.
--dockerfile <path>	Dockerfile path (inside the folder or the repository).
--context <path>	Build context inside the repository.
--build	Build on Lantfly from the Git origin remote and stream the build log.
--no-upload	Do not upload the folder; print docker build and docker push commands instead.

What push does:

1. Finds the actor by name among your own actors. Creates it (name, title, description, image, input schema) or updates it.
2. Creates or updates the version, with the input schema, dataset schema and output schema from .actor/.
3. Picks the image: --image, image in actor.json, the actor's current image, or lantfly/<namespace>/<name> (your namespace comes from your account).
4. Gets the image built, in one of three ways:
   • Upload the folder (default, when the folder has its Dockerfile). The CLI packs the folder into a .tar.gz, uploads it, streams the build log and exits non-zero if the build fails. Left out of the archive: what .gitignore and .dockerignore list, plus .git/, node_modules/, storage/, .env and .env.* (not .env.example), *.log and symlinks. The Dockerfile and .actor/ always go. The archive must stay under 50 MB compressed, and the Dockerfile must be inside the folder.
   • Build from Git (--git-url or --build). An SSH remote is changed to HTTPS; the repository must be public. The Dockerfile and context paths come from the folder's place in the repository; --dockerfile and --context override them.
   • Build it yourself (--no-upload, or no Dockerfile in the folder). The CLI prints the docker build and docker push commands. Then run lantfly push --image-tag <tag>.

If builds are not available for your account, push says so and prints the docker commands. See Builds and versions.

lantfly call <actor>

Starts a run, streams its log and prints the result. Name the actor by id, username~name, username/name or an alias.

Terminal

lantfly call lantfly~hello --input '{"count": 5}'
lantfly call lantfly~web-scraper -i input.json --memory 1024 --timeout 300 --build latest --max-items 100
lantfly call lantfly~hello --output-dataset > items.json   # the log goes to stderr
lantfly call lantfly~hello --no-wait --json                 # start it and print the run

Flag	Meaning
-i, --input-file <file>	Input JSON file.
--input <json>	Input as a JSON string. Use either this or --input-file. The input must be a JSON object.
--memory <mb>	Memory in MB.
--timeout <secs>	Timeout in seconds.
--build <tag>	Version or image tag to run (latest: the default version).
--max-items <n>	Stop paying past this many dataset items.
--wait	Wait for the run to finish (default).
--no-wait	Start the run and return.
--output-dataset	Print the default dataset items as JSON when the run ends.

At the end, call prints the status and the number of dataset items. It exits with code 1 when the run did not succeed.

lantfly runs

Terminal

lantfly runs ls --actor lantfly~hello --status SUCCEEDED --limit 20
lantfly runs info <runId>
lantfly runs log <runId> --follow
lantfly runs abort <runId>
lantfly runs resurrect <runId>

Command	Flags	What it does
runs ls	--actor <actor>, --status <status>, --limit <n>	List recent runs.
runs info <runId>		Show a run.
runs log <runId>	-f, --follow	Print the run log; with --follow, keep printing until the run ends.
runs abort <runId>		Abort a run.
runs resurrect <runId>		Run a finished run again on the same storages.

lantfly actors and lantfly builds

Command	Flags	What it does
actors ls	--my, --limit <n>	List the actors you can see; --my only those of the acting account.
builds ls <actor>	--limit <n>	List an actor's builds, newest first.
builds log <actor> <buildId>	-f, --follow	Print a build log; with --follow, until the build ends.

lantfly datasets get-items

Terminal

lantfly datasets get-items <datasetId> --format csv --out items.csv
lantfly datasets get-items --actor lantfly~web-scraper --format json   # the actor's last run
lantfly datasets get-items --run <runId> --fields url,title --limit 100

Flag	Meaning
[datasetId]	The dataset. Or use --actor or --run.
--actor <actor>	The default dataset of the actor's last run.
--run <runId>	A run's default dataset.
--format <format>	json (default), jsonl, csv, xlsx, html, xml, rss.
--out <file>	Write to a file instead of stdout. Required for xlsx (binary).
--fields <a,b>	Only these fields.
--omit <a,b>	Leave out these fields.
--limit <n>	At most n items.
--offset <n>	Skip n items.
--clean	Skip empty items and hidden fields.

lantfly kv

Terminal

lantfly kv get <storeId> OUTPUT --out output.json
lantfly kv set <storeId> INPUT input.json      # a file is uploaded as is (type from its extension)
lantfly kv set <storeId> NOTE 'hello'          # a value: JSON if it parses, text otherwise

Command	Flags	What it does
kv get <storeId> <key>	--out <file>	Print or save a record.
kv set <storeId> <key> <fileOrValue>	--content-type <type>	Store a file, or a value (JSON when it parses, text otherwise).

Scripts and exit codes

• With --json, JSON dataset items print as the list of items.
• A failure prints the API's error as code: message, for example not_found: Actor was not found. Validation errors add the field messages. With --json, the CLI also prints {"error":{"code","message"}} on stdout.
• Exit codes:

Code	Meaning
0	Success.
1	API error, or a run or build that failed.
2	Usage error (unknown flag, missing argument).

Use Lantfly from AI clients

The CLI token also works for the Lantfly MCP server. See MCP.