CLI

The CLI is the quickest way to move lots of data in and out of EmbodiFlow from a terminal or a script. It talks to the same public REST API as the console, and it installs one program under two names: embodiflow and the shorter ef.

Output is JSON whenever stdout isn't a terminal, so scripts and agents can parse it directly. Add --json to force JSON, or --output table for a readable table. Every command also accepts --api-base-url <url> and --profile <name>.

Install

The package is @embodiflow/cli, published to the organization's GitHub Packages registry, so you need read access to that registry.

npm install --global @embodiflow/cli --registry=https://npm.pkg.github.com
embodiflow --help

Sign in

auth login opens your browser so you can sign in there. In automation, pass a personal access token instead: --pat lets you paste it, and --pat-stdin reads it from standard input. The CLI talks to the production API (https://api.embodiflow.io) unless you pass --base-url.

embodiflow auth login --base-url https://api.embodiflow.io
embodiflow whoami --json

whoami shows who you are signed in as: email, active team, token kind, scopes and expiry. embodiflow auth logout removes the saved credential, and embodiflow config doctor checks that the CLI can reach everything it needs.

Main commands

Projects

embodiflow projects list --json

embodiflow projects create --name "Pick and place"

Upload

embodiflow uploads create --project-id <project-id> --source-path ./recordings

uploads create takes a project UUID (--project-id) and a folder, and every recording folder inside it becomes a recording. Want to see what would happen first? uploads plan takes the same --source-path and prints a read-only plan without creating anything.

To upload a single recording under a name you choose, use recordings upload <path>. It takes the project as --project <team>/<project> (or a project UUID), and --name sets the recording name.

embodiflow recordings upload ./recordings/rec-0001 --project <team>/<project> --name rec-0001

Workflow runs

embodiflow workflow runs list --project-id <project-id>

embodiflow workflow runs wait <run-id>

workflow runs wait keeps polling until the run finishes, which makes it handy at the end of an upload script.

Exports and downloads

embodiflow exports create --project-id <project-id> --version-number 1

embodiflow versions download <team>/<project>@1 --format lerobot-v3

exports status, exports wait and exports download take --project-id, --version-number and --export-id. If you have a team/project@n reference and need the ids behind it, resolve <ref> looks them up.

Training

embodiflow training jobs list --project-id <project-id>

embodiflow training checkpoints download --job <job-id> -o weights.tar

training checkpoints download streams the job's last checkpoint to disk and verifies its size and checksum. Use --checkpoint to pick another checkpoint key.

Webhooks

embodiflow webhook-endpoints create --url https://example.com/hooks --event-types workflow.run.succeeded

The signing secret is shown only once, so save it right away. Signature verification explains how to check each delivery.

Discover more

embodiflow schema commands --json
embodiflow <command> --help

schema commands prints the full machine-readable list of commands and flags. It's the source this page is written from, so when in doubt, it wins.

Exit codes

Scripts can rely on these. A command that fails always exits non-zero.

• 0 success.
• 1 the command failed: an API error, a validation error, something not found, or you're not signed in.
• 2 usage error: an unknown command or a missing argument.
• 3 uploads create stored every file, but processing didn't start. Fix the reason it prints, then run uploads create --resume to submit again without re-uploading.