@aiagenttask/cli

Command-line interface for AgentTask — task management for humans & AI agents.

Install

npm i -g @aiagenttask/cli
# or
pnpm add -g @aiagenttask/cli

Two binaries are registered: agenttask and the short alias atask.

Quick start

# 1. Check API connectivity
atask health

# 2. Log in (opens browser / prompts for credentials)
atask auth login

# 3. List workspaces
atask workspace list

# 4. Create a task
atask task create --title "Ship CLI release" --workspace <id>

# 5. List tasks
atask task list

Configuration

Config is persisted to ~/.agenttask/config.json after atask auth login (permissions 0600). It holds token, refreshToken, apiUrl, and the default workspaceId.

Resolution order

The CLI resolves settings from highest → lowest priority. The first source that provides a value wins.

API base URL (--api-url)

| # | Source | Example | |---|---|---| | 1 | CLI flag | atask task list --api-url https://api.example.com | | 2 | Stored config | ~/.agenttask/config.json → apiUrl (written by auth login) | | 3 | Env var | AGENTTASK_API_URL=https://api.example.com | | 4 | Built-in default | https://api.agenttask.cc |

Auth token

| # | Source | Example | |---|---|---| | 1 | Stored config | ~/.agenttask/config.json → token (written by auth login) | | 2 | Env var | AGENTTASK_API_KEY=at_xxx |

On 401, CLI auto-refreshes using refreshToken from stored config and rewrites it transparently. Env-sourced tokens are not refreshed (there's no refresh token on disk to rotate) — use a long-lived API key (at_…) for CI.

Default workspace (--workspace)

| # | Source | |---|---| | 1 | CLI flag --workspace <id> | | 2 | Stored config workspaceId (set via atask workspace use <id>) | | 3 | Env var AGENTTASK_WORKSPACE_ID |

Supported env vars

| Env var | Read by | Purpose | Default | |---|---|---|---| | AGENTTASK_API_URL | CLI + MCP | API base URL fallback when no stored config | https://api.agenttask.cc | | AGENTTASK_API_KEY | CLI + MCP | Bearer token fallback when no stored token | — | | AGENTTASK_WORKSPACE_ID | CLI + MCP | Default workspace fallback | — |

CI recipe — no auth login needed, just set env:

export AGENTTASK_API_KEY=at_xxxxxxxxxxxx
export AGENTTASK_WORKSPACE_ID=ws_xxxxxxxxxxxx
atask task list --json

Command groups

| Group | Purpose | |---|---| | auth | Login, logout, whoami | | workspace | List/create/switch workspaces | | task | CRUD tasks, status, assignees | | todo | Subtask checklist on a task | | comment | Task comments | | label | Task labels | | search | Full-text search across tasks | | kg | Knowledge graph queries | | api-key | Manage personal API keys | | agent | Manage AI agents | | ai-provider | Configure AI providers (OpenAI, Anthropic, ...) | | health | Ping API server |

Run atask <group> --help to see subcommands, or atask --help for the full tree.

JSON output

Most read commands support --json for machine consumption:

atask task list --json | jq '.[] | select(.status == "in_progress")'

Self-hosting

If you run your own AgentTask API:

export AGENTTASK_API_URL=https://api.your-domain.com
atask auth login

Links

• Website: https://agenttask.cc
• Issues: https://github.com/digitopvn/agenttask/issues
• Source: https://github.com/digitopvn/agenttask/tree/main/packages/cli

License

MIT