Features

Configuration

Configure Asana CLI with environment variables and config files

Configuration

Customize Asana CLI behavior with environment variables and configuration files.

Configuration File

Asana CLI stores settings in ~/.asana-cli/config.json:

{
  "accessToken": "your_access_token",
  "refreshToken": "your_refresh_token",
  "authType": "oauth",
  "workspace": "default_workspace_id",
  "expiresAt": 1234567890
}

Location

Linux/macOS: ~/.asana-cli/config.json
Windows: %USERPROFILE%\.asana-cli\config.json

Structure

Field	Type	Description
`accessToken`	string	Current access token
`refreshToken`	string	OAuth refresh token (OAuth only)
`authType`	string	Authentication type: `"oauth"` or `"pat"`
`workspace`	string	Default workspace ID
`expiresAt`	number	Token expiration timestamp (OAuth only)

Environment Variables

Authentication Variables

# OAuth Configuration
ASANA_CLIENT_ID=your_client_id
ASANA_CLIENT_SECRET=your_client_secret

# Personal Access Token
ASANA_ACCESS_TOKEN=your_token

# Default Workspace
ASANA_WORKSPACE=workspace_id

Usage Priority

Environment variables override config file settings:

Command-line flags (highest priority)
Environment variables
Config file
Default values (lowest priority)

Example

# Set in environment
export ASANA_WORKSPACE=123456789

# Override in command
bun run dev task list -a me -w 987654321

Setting Default Workspace

bun run dev auth login --token YOUR_TOKEN -w WORKSPACE_ID

Manually edit ~/.asana-cli/config.json:

{
  "workspace": "your_workspace_id"
}

Or set environment variable:

export ASANA_WORKSPACE=your_workspace_id

Using .env Files

Bun automatically loads .env files from the project root.

Create .env File

cp .env.example .env

Edit .env

# OAuth (if using OAuth)
ASANA_CLIENT_ID=your_client_id
ASANA_CLIENT_SECRET=your_client_secret

# Or PAT (if using Personal Access Token)
ASANA_ACCESS_TOKEN=your_token

# Default workspace
ASANA_WORKSPACE=your_workspace_id

Never commit .env files: Add .env to your .gitignore to prevent accidental commits.

Encrypted Environment Variables with dotenvx

This project supports encrypted environment variable management using dotenvx.

Why Use dotenvx?

Security: Encrypt sensitive credentials before committing
Version Control Safe: Commit encrypted .env files
Team Collaboration: Share encrypted credentials safely
Multiple Environments: Manage dev, staging, prod environments

Setup

Create .env file:

cp .env.example .env

Add your credentials:

# OAuth (optional)
ASANA_CLIENT_ID=your_client_id
ASANA_CLIENT_SECRET=your_client_secret

# PAT (optional, alternative to --token)
ASANA_ACCESS_TOKEN=your_token

# Default workspace (optional)
ASANA_WORKSPACE=workspace_id

Encrypt environment variables (recommended):

bun run env:encrypt

This creates .env.keys with encryption keys and encrypts your .env file.

Run with encrypted environment:

# Development mode
bun run dev:secure auth login

# E2E tests
bun run test:e2e:secure

Available Scripts

# Encrypt .env file
bun run env:encrypt

# Decrypt .env file (view encrypted values)
bun run env:decrypt

# Run commands with encrypted environment
bun run dev:secure <command>
bun run test:e2e:secure

dotenvx Configuration

The project includes dotenvx configuration in .env.example:

Environment variables for OAuth and PAT
Workspace configuration
Secure credential management

Learn more: dotenvx Documentation

Best Practices with dotenvx

Encrypt before committing: Always encrypt sensitive data
Keep .env.keys secure: Never commit this file
Add to .gitignore:
```
.env
.env.keys
```
Use encrypted .env in CI/CD: Safe to commit encrypted versions
Rotate encryption keys regularly: Update .env.keys periodically

Shell Aliases

Create shortcuts for common commands:

Bash/Zsh

Add to ~/.bashrc or ~/.zshrc:

# Shortcuts
alias asana="bun run dev"
alias asana-me="bun run dev task list -a me"
alias asana-create="bun run dev task create"
alias asana-done="bun run dev task complete"

# With default workspace
alias asana-list="bun run dev task list -a me -w YOUR_WORKSPACE_ID"

Usage

# Instead of: bun run dev task list -a me -w WORKSPACE_ID
asana-me

# Instead of: bun run dev task create -n "Task"
asana-create -n "New task"

# Instead of: bun run dev task complete TASK_ID
asana-done TASK_ID

Using Compiled Binary

After building the binary:

bun run build

System-wide Installation

# Make executable
chmod +x asana

# Move to PATH
sudo mv asana /usr/local/bin/

# Now use from anywhere
asana task list -a me

Configuration

The compiled binary uses the same config file:

~/.asana-cli/config.json
Environment variables
.env files in current directory

Advanced Configuration

Custom Config Location

Currently not supported, but you can use environment variables to achieve similar results:

export ASANA_ACCESS_TOKEN=$(cat /path/to/token.txt)
export ASANA_WORKSPACE=$(cat /path/to/workspace.txt)

Multiple Workspaces

Switch between workspaces:

# Workspace A
export ASANA_WORKSPACE=workspace_a_id
bun run dev task list -a me

# Workspace B
export ASANA_WORKSPACE=workspace_b_id
bun run dev task list -a me

Or use -w flag:

bun run dev task list -a me -w WORKSPACE_A_ID
bun run dev task list -a me -w WORKSPACE_B_ID

Multiple Accounts

Use separate config files (requires scripting):

# Account 1
cp ~/.asana-cli/config.json ~/.asana-cli/config.account1.json

# Account 2
bun run dev auth logout
bun run dev auth login --token ACCOUNT2_TOKEN
cp ~/.asana-cli/config.json ~/.asana-cli/config.account2.json

# Switch accounts
cp ~/.asana-cli/config.account1.json ~/.asana-cli/config.json

Best Practices

Recommendations

Use .env for Development: Keep credentials in .env file locally
Use Config File for Production: Store tokens in ~/.asana-cli/config.json
Set Default Workspace: Reduces command verbosity
Create Aliases: Speed up common operations
Keep Tokens Secure: Never commit or share credentials
Use Environment Variables in CI/CD: For automated workflows ::

Troubleshooting

Config File Not Found

The config file is created automatically on first login:

bun run dev auth login --token YOUR_TOKEN

Permission Denied

Ensure config directory has proper permissions:

chmod 700 ~/.asana-cli
chmod 600 ~/.asana-cli/config.json

Environment Variables Not Loading

Check .env file location (must be in project root) and format:

# Correct
ASANA_ACCESS_TOKEN=token

# Incorrect (quotes usually not needed)
ASANA_ACCESS_TOKEN="token"

Authentication - Login methods
Getting Started - Initial setup
Quick Start - Basic commands

Edit this pageorReport an issue

Authentication

Authentication methods and credential management for Asana CLI

Subtasks & Dependencies

Build task hierarchies and dependency relationships with Asana CLI