AI Agents

AI coding agents can use the Plotly Cloud CLI to build, iterate on, and deploy Dash apps. This page covers how to set up your environment so agents can publish to Plotly Cloud.

Overview

AI agents that have shell access—such as Claude Code, Cursor, Windsurf, and GitHub Copilot—can run CLI commands on your behalf. With the Plotly Cloud CLI installed and authenticated, an agent can:

• Scaffold and develop a Dash app
• Run it locally with plotly app run
• Publish it to Plotly Cloud with plotly app publish
• Check deployment status with plotly app status

Setup

1. Install the CLI

Make sure dash[cloud] is installed in the environment your agent uses:

pip install "dash[cloud]"

2. Authenticate

Agents cannot complete the browser-based login flow on their own, so log in before starting your agent session:

plotly user login

The agent will then use your existing credentials for any CLI commands it runs. This means the agent operates with your personal permissions—it can access any apps and teams that you have edit permissions on.

Recommended: Always use personal authentication (plotly user login) with AI agents rather than API keys. This ensures the agent’s actions are scoped to your own permissions and are traceable to your account.

Example: Building and Deploying with an Agent

A typical agent workflow looks like this:

1. Ask the agent to create a Dash app:
   Create a Dash app that shows a scatter plot of the iris dataset (px.data.iris()) with dropdowns to select the x and y columns.

The agent writes the code and can run it locally:
bash plotly app run

2. Once you’re satisfied, ask the agent to publish:
   Publish this to Plotly Cloud as iris-explorer.

The agent runs:
bash plotly app publish --name iris-explorer

Tips

• Iterate locally first. Have the agent use plotly app run during development and only plotly app publish when you’re ready to deploy.
• Stay in the project directory. Commands like plotly app status read from plotly-cloud.toml in the current directory. If the agent changes directories, these commands will fail.
• Specify the app name on first publish. Include --name when publishing so the agent doesn’t prompt for input interactively. After the first publish, the name is saved in plotly-cloud.toml.
• The CLI polls automatically. plotly app publish waits for the deployment to finish by default, so the agent will know when the app is live without any extra steps.
• Re-publishing updates the app in place. After the first publish, the agent can run plotly app publish without --name to push updates to the same app.
• Set a readable app URL after first publish. The first publish assigns a UUID as the app URL. On paid plans, have the agent edit app_url in plotly-cloud.toml to a human-readable slug and re-publish. See Custom App URLs.
• Apps are private by default. Published apps are only accessible to you and your team members. Head to Plotly Cloud to update the access settings or copy the app URL for sharing.
• Give agents access to the CLI reference. Point agents to the CLI reference so they know the available commands and options.

Agent-Specific Notes

Claude Code

Claude Code has shell access and can run plotly commands in its tool calls. Install and authenticate before starting your session.

Cursor / Windsurf

These IDE-based agents run commands in the integrated terminal. Ensure dash[cloud] is installed in the Python environment selected by your IDE.

GitHub Copilot (in VS Code)

Copilot’s terminal agent can run CLI commands when you use @terminal. Make sure your VS Code terminal has dash[cloud] installed and is authenticated.

Remote / Headless Agents

Agents running in non-interactive environments (containers, cloud VMs) cannot complete the browser-based OAuth flow required by plotly user login. Use an API key for authentication instead.

Troubleshooting

"Invalid token - credentials cleared"

This error message means that your session has expired. Run plotly user login again yourself, then resume the agent session. You can verify credentials are working with plotly user whoami.