[New] Asana CLI

Asana Community API & Developers Changelog
1

Summary

We’re introducing the Asana CLI, a command-line interface for the Asana API. It gives developers, scripts, and AI agents a way to read and update Asana resources directly from a terminal, without writing a separate application or learning a client library first.

Every command follows the same shape – a resource, then a verb, then flags:

asana-cli tasks get --task 1201234567890123

Key highlights:

  • Resource-oriented commands: Work with tasks, projects, and other resources using verbs like get, list, and create. You don’t need to know endpoint paths or request body shapes.
  • Built for scripts and automation: JSON output by default, with tabular formats for reading results on screen.
  • Agent-ready: Any agent that can run a shell command can call the Asana API through the CLI, authenticated with a token supplied through an environment variable.
  • Discoverable: Scoped --help at every level, suggestions for mistyped commands, and shell autocomplete for zsh, bash, and PowerShell.
  • Input validation: Structured JSON inputs are validated against the API schema before any request is sent.

Who can use this

The CLI is intended for:

  • Developers who want to inspect or change Asana data from a terminal for one-off tasks
  • Teams automating API operations in shell scripts or CI pipelines
  • AI agents with terminal access, running locally or in a cloud environment, that need to call the Asana API as part of their workflows

This is not a breaking change. Existing API and SDK integrations continue to work without changes. The CLI is an additional way to use the Asana API alongside our SDKs and the MCP server, not a replacement for either.

Timeline

This is available now!

Usage

Install

Install the CLI from npm. Node.js 22 or newer is required.

npm install --global @asana-api/cli

Authenticate

The CLI reads an access token from ASANA_ACCESS_TOKEN by default. You can select another environment variable using the token_env_var configuration setting (see Asana CLI on npm to learn more). It does not store credentials, prompt for them, or accept them as command arguments.

export ASANA_ACCESS_TOKEN="your_token_here"

The CLI accepts a personal access token (PAT), a Service Account token, or an OAuth access token. Requests run with that token’s identity and permissions: PATs and OAuth access tokens act on behalf of the associated user, and Service Account tokens act as the Service Account.

To check which token the CLI is using and who it authenticates as:

asana-cli auth status

If no usable token is found, the CLI tells you which environment variable it looked for and how to supply one.

Explore commands

Help is available at every level, so you can discover resources, verbs, and flags without leaving the terminal:

asana-cli --help                # list available resources
asana-cli tasks --help          # list verbs for one resource
asana-cli tasks list --help     # usage and flags for one command

Flags in help output are grouped by role (for example: target, context, filter, pagination, and output), and usage lines show the valid flag combinations for each command.

Read data

A single command can cover several related API endpoints. The flags you pass determine which endpoint is called:

# List tasks in a project (GET /projects/{project_gid}/tasks)
asana-cli tasks list --project 1209876543210987

# List your tasks in a workspace (GET /tasks)
asana-cli tasks list --workspace 1200000000000001 --assignee me

# Get a single task (GET /tasks/{task_gid})
asana-cli tasks get --task 1201234567890123

Create or update data

Request body properties are exposed as flags:

asana-cli tasks create \
  --workspace 1200000000000001 \
  --name "Fix the login bug" \
  --projects 1209876543210987

For structured inputs, pass JSON. The CLI validates it against the API schema before sending the request, and validation errors name the flag and the JSON path that failed:

asana-cli projects duplicate \
  --project 1209876543210987 \
  --name "Q4 Launch (copy)" \
  --include task_dates \
  --schedule-dates '{"should_skip_weekends":true,"start_on":"2026-12-01"}'

Asynchronous operations

Some operations, like duplicating a project, run asynchronously and return a Job. Commands that return a Job accept --wait to poll until the job succeeds or fails. The default wait limit is 60 seconds; use --max-wait to change it. Reaching that limit stops the CLI from waiting, but does not cancel the job.

asana-cli projects duplicate --project 1209876543210987 --name "Q4 Launch (copy)" --wait --max-wait 120

You can also wait on any existing job by its GID with asana-cli jobs wait. Run asana-cli jobs wait --help for usage.

Output formats

Commands return JSON by default, so results can be piped into tools like jq or consumed by an agent. Use --output to choose a different format:

asana-cli tasks list --project 1209876543210987 --output table
Value Best for
json (default) Scripts, agents, and piping into other tools
json-pretty Reading results in a terminal
table Reading results in a terminal
csv Spreadsheets and line-oriented tools

Tabular formats show top-level fields. To include a specific nested field, request it with --opt-fields:

asana-cli tasks list --project 1209876543210987 --output table --opt-fields name,assignee.name

Errors and exit codes

  • Mistyped commands return a suggestion for the closest match (for example, tasks gets suggests tasks get).
  • Missing or invalid input returns the command’s usage help.
  • API errors are passed through from the API.

All errors exit with a status code, so scripts and agents can detect failures reliably.

Using the CLI with AI agents

Agents run CLI commands using the token from the selected environment variable. Every request uses that token’s identity and permissions. Choose the token based on how much access the agent needs:

  • Organization-managed agents that need organization-wide access: A dedicated, administrator-managed Service Account may be a suitable option. Service Accounts require an eligible Enterprise plan, and standard task and project operations require Full Permissions.
  • Agents that need narrower access: Use an OAuth access token restricted to the scopes the agent needs. This release accepts OAuth access tokens but does not include a built-in OAuth login flow or automatic token refresh.
  • Agents acting on your or bot’s account behalf: Use a personal access token (PAT). A PAT acts as the user who created it and carries that user’s full access, so the agent can do anything this user can do in Asana.

Delete commands do not ask for confirmation. The CLI never prompts, so commands behave the same whether a person or an agent runs them. Before letting an agent run write or delete commands:

  • Verify target GIDs and inputs
  • Restrict the token’s permissions to what the agent needs
  • Configure any approval steps in the system running the agent

Deleted tasks, projects, and messages can be restored from Asana’s Deleted view within 30 days, unless permanently deleted sooner. Other resources may behave differently. See recovering deleted items for details.

FAQ

Which plans can use the CLI?

The CLI is available on all Asana plans, including the free Personal plan. Access to specific endpoints and resources depends on your Asana plan, your token’s permissions, and your organization’s API controls.

Can admins control CLI access?

Existing API controls apply, including token restrictions, revocation, expiration policies, and app approvals, depending on your organization’s plan. There is no separate CLI admin setting. See app management and integrations.

Does the CLI store my token?

No. The CLI reads the token from the environment on each run and never writes it to disk, logs, or verbose output. Keep in mind that an exported environment variable is available to other processes started from the same shell.

Should I use the CLI, an SDK, or the MCP server?

They serve different contexts. Use an SDK when building an application, the MCP server when connecting an AI assistant that speaks MCP, and the CLI for terminal work, scripts, and agents that run shell commands.

Resources

Questions and feedback

We’d love to hear what you’re building with the Asana CLI. Please reply here with your feedback or questions.

3 Likes
[New] Asana CLI now available
2

Bravo! :clap: