CLI

Install the World Labs CLI with npm install -g @worldlabsai/cli, then install its skill with worldlabs skills install --client codex.

Run worldlabs auth login in your own terminal so I can enter my API key privately. Do not ask me to share the key in chat. Then verify setup with worldlabs auth status and worldlabs tasks list.

Use the World Labs Developer API from a terminal or coding agent. The CLI uses your project's API key and billing. It requires Node.js 22 or newer.

Install and sign in

npm install -g @worldlabsai/cli && worldlabs setup

On Windows, run these commands in Command Prompt.

Setup opens the API keys page. Create a key for your project and paste it into the hidden terminal prompt. Keep the key out of agent chats. Setup can also install the World Labs skill for your coding agent. Use --client <agent> to select an agent explicitly. Pass --yes to accept prompts during skill installation.

Verify your connection and list the task names supported by the CLI:

worldlabs auth statusworldlabs tasks list

A successful status check confirms asset access. Individual tasks can require additional key permissions or beta access.

Install agent skills

Install the World Labs skill from worldlabsai/skills using Skills CLI. Installation is global and requires network access, npm, and Git. The installer detects available agents and handles client selection:

worldlabs skills install

To choose an agent directly, pass --client:

worldlabs skills install --client cursorworldlabs skills install --client gemini-cli

Pass --yes to accept installer prompts. Run the install command again to refresh the World Labs skill. To remove it, select the agent you installed it for:

worldlabs skills uninstall --client cursor

Start a new agent session after installation to load the skill. Older CLI-managed installations are moved to a local backup, whose path is printed in the terminal. If installation fails or is cancelled, the CLI waits for the installer to stop, then restores the old skill unless the installer has already written a replacement; in that case, it keeps both copies and reports the backup path. If an older installation has local edits, installation stops and leaves it in place.

If the CLI cannot confirm that the installer has stopped, it retains the backup without restoring it. Stop any remaining installer processes before restoring that backup manually.

Before choosing model inputs, calculating cameras, or combining tasks, read How To Use Atlas. The skill links to this maintained guide.

Submit JSON and save results

Upload your image:

worldlabs assets upload photo.jpg --json

The CLI picks the content type from the file extension for .jpg, .jpeg, .png, .webp, .exr, .mp4, .glb, .ply, and .spz. For any other file, pass --mime. Upload a linear-depth EXR the same way:

worldlabs assets upload depth.exr --json

Put the returned asset ID in request.json:

1{2  "frames": [{ "imageAsset": { "assetId": "<uploaded-asset-id>" } }]3}

Submit the file and wait for the result:

worldlabs tasks run images2PosedRGBD --request request.json --wait --json > result.json

Use --request - to read JSON from standard input. For example, stream the same file into the command:

worldlabs tasks run images2PosedRGBD --request - --wait --json < request.json > result.json

Results go to stdout. Progress messages and the retry key go to stderr, so result.json contains only the result. If submission is interrupted, retry with the original request and --idempotency-key <printed-key>.

A wait timeout stops the local command without cancelling server work. Resume with worldlabs operations wait <operation-id> --json. Check a completed operation for error before using its response. Download output assets with worldlabs assets download <asset-id> --out result.png.

Credentials

Login saves the API key in a plaintext file in your user configuration directory. worldlabs auth status reports its location. Use WLT_API_KEY for automation; it takes precedence over saved credentials.

To save a key without the hidden prompt, for example from a secret manager or where no one can type into the terminal, pipe it to --api-key-stdin. The key stays out of the command line and shell history:

worldlabs auth login --api-key-stdin < key.txt

worldlabs setup --api-key-stdin does the same during setup.

worldlabs auth logout removes the local key. To disable it everywhere, revoke it on the API keys page.

See Authentication for key permissions and Errors and retries for recovering interrupted requests.