How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/blaxel-ai/agent-skills --skill blaxel-cliBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
Blaxel CLI
A CLI to manage Blaxel cloud resources from the command line: agents, sandboxes, jobs, MCP servers, drives, and more.
Prerequisites
The bl command must be available on PATH. To check:
bl versionIf not installed, use the official installer for this operating system.
macOS or Linux:
curl -fsSL https://blaxel.ai/install.sh | shWindows PowerShell:
irm https://blaxel.ai/install.ps1 | iexFollow the installer's PATH or shell-reload instructions, then complete setup:
bl setupSetup installs the Blaxel skills and configures supported coding agents. In a terminal, it also offers browser login. If the installer already completed setup, verify the result instead of repeating it.
When running without a terminal, use bl setup --yes. Setup skips browser login in that environment. If sign-in is still needed, run bl login, present its secure browser URL, and continue after the user approves it. Confirm the selected workspace from command output; do not guess a workspace name or ask for pasted credentials.
For unattended automation, use an existing BL_API_KEY and BL_WORKSPACE supplied securely through the environment. Commands can use these directly; do not start browser login or persist the key in agent configuration.
Verify the installed command and active workspace:
bl version
bl workspaces --currentTreat empty workspace output as incomplete sign-in.
Global Flags
All commands support these flags:
| Flag | Description |
|---|---|
-o, --output <format> | Output format: pretty, yaml, json, table |
-w, --workspace <name> | Override workspace for this command |
-v, --verbose | Enable verbose output |
-u, --utc | Enable UTC timezone |
--skip-version-warning | Skip version warning |
Non-Interactive Mode
For commands that prompt for input (confirmations, selections), add -y or --yes to auto-confirm. This is required when running in non-interactive / no-TTY environments (scripts, CI, agents).
Available Commands
bl apply # Apply configuration changes to resources declaratively using YAML files.
bl chat # Start an interactive chat session with a deployed agent.
bl connect # Open an interactive terminal session to a sandbox
bl delete # Delete Blaxel resources from your workspace.
bl deploy # Deploy your Blaxel project to the cloud.
bl drive # Manage drives and drive mounts on sandboxes.
bl fork # Create a new sandbox or application by forking an existing sandbox.
bl get # Retrieve information about Blaxel resources in your workspace.
bl login # Authenticate with Blaxel to access your workspace.
bl logout # Remove stored credentials for a workspace.
bl logs # View logs for Blaxel resources.
bl mcp # Serve the hosted Blaxel MCP tools over stdio using your existing bl login.
bl new # Create a new Blaxel resource from templates.
bl push # Build and push a container image to the Blaxel registry without creating a deployment.
bl run # Execute a Blaxel resource with custom input data.
bl serve # Start a local development server for your Blaxel project.
bl setup # Set up everything Blaxel needs on this machine, then log in.
bl share # Share Blaxel resources with other workspaces in your account.
bl skills # Manage the Blaxel agent skills installed for your coding agents.
bl token # Retrieve the authentication token for the specified workspace.
bl unshare # Remove shared Blaxel resources from other workspaces.
bl upgrade # Upgrade the Blaxel CLI to the latest version.
bl version # Print the version number
bl workspaces # List and manage Blaxel workspaces.Reference Documentation
- apply - Apply configuration changes to resources
declaratively using YAML files.
- chat - Start an interactive chat session with a deployed
agent.
- connect - Open an interactive terminal session to a
sandbox
- delete - Delete Blaxel resources from your workspace.
- deploy - Deploy your Blaxel project to the cloud.
- drive - Manage drives and drive mounts on sandboxes.
- fork - Create a new sandbox or application by forking an
existing sandbox.
- get - Retrieve information about Blaxel resources in your
workspace.
- login - Authenticate with Blaxel to access your
workspace.
- logout - Remove stored credentials for a workspace.
- logs - View logs for Blaxel resources.
- mcp - Serve the hosted Blaxel MCP tools over stdio using
your existing bl login.
- new - Create a new Blaxel resource from templates.
- push - Build and push a container image to the Blaxel
registry without creating a deployment.
- run - Execute a Blaxel resource with custom input data.
- serve - Start a local development server for your
Blaxel project.
- setup - Set up everything Blaxel needs on this machine,
then log in.
- share - Share Blaxel resources with other workspaces in
your account.
- skills - Manage the Blaxel agent skills installed for
your coding agents.
- token - Retrieve the authentication token for the
specified workspace.
- unshare - Remove shared Blaxel resources from other
workspaces.
- upgrade - Upgrade the Blaxel CLI to the latest
version.
- version - Print the version number
- workspaces - List and manage Blaxel workspaces.
Discovering Options
To see available subcommands and flags, run --help on any command:
bl --help
bl deploy --help
bl get --help
bl get agents --helpCommon Workflows
Create a sandbox, run a command, and get its logs
# 1. Create a sandbox with bl apply
bl apply -f - <<EOF
apiVersion: blaxel.ai/v1alpha1
kind: Sandbox
metadata:
name: my-sandbox
spec:
runtime:
image: blaxel/base-image:latest
memory: 2048
lifecycle:
expirationPolicies:
- type: ttl-idle
value: 1h # Delete after 1 hour of inactivity. Units: h, d, w
action: delete
EOF
# 2. Retrieve sandbox configuration
bl get sandbox my-sandbox
# 3. Execute a command in the sandbox and get stdout of the command
bl run sandbox my-sandbox --path /process --data '{"command": "echo hello world", "name": "my-cmd", "waitForCompletion": true}'
# 4. Retrieve the logs for that command in case stdout was not sufficient
bl logs sandbox my-sandbox my-cmdRun a complex command in a sandbox (agent guideline)
bl run sandbox ... --path /process --data '<json>' requires the JSON payload to survive shell quoting. As soon as the command embeds nested quotes, backslashes, multiple lines, or interpreters like sh -lc / python3 -c, inline --data becomes brittle and the API rejects the request with 400 Bad Request: invalid character ... in string escape code.
Decision rule for an agent:
- Command has no single quotes, no backslashes, no newlines → use
--data '{"command": "...", "waitForCompletion": true}' directly.
- Anything more complex (nested quotes, escapes, multiline, scripts) → **write
the JSON payload to a file** with your Write/file-creation tool (this bypasses the shell entirely), then run with --file.
# Step 1 — agent writes /tmp/process.json with content like:
# {
# "command": "sh -lc 'python3 -c \"print(\\\"hello\\\")\"'",
# "name": "cve-check",
# "waitForCompletion": true
# }
#
# Step 2 — execute it
bl run sandbox my-sandbox --path /process --file /tmp/process.jsonDeploy an agent
bl new agent my-agent
cd my-agent
bl serve --hotreload # Test locally
bl deploy # Deploy to cloud
bl chat my-agent # Chat with itManage sandboxes
bl get sandboxes # List all
bl get sandbox my-sandbox --watch # Watch status
bl connect sandbox my-sandbox # Interactive terminal
bl logs sandbox my-sandbox --follow # Stream logs
bl delete sandbox my-sandbox # Clean upMulti-workspace deployment
bl workspaces dev # Switch to dev
bl deploy # Deploy to dev
bl workspaces prod # Switch to prod
bl deploy # Deploy to prod
