{"id":48719882,"url":"https://github.com/dhanesh/workflowy_cli","last_synced_at":"2026-04-11T19:12:27.887Z","repository":{"id":349038545,"uuid":"1200820468","full_name":"dhanesh/workflowy_cli","owner":"dhanesh","description":"Token-efficient Workflowy CLI for AI agents. Compact JSON output optimized for LLM context windows.","archived":false,"fork":false,"pushed_at":"2026-04-03T22:01:27.000Z","size":121,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T23:25:34.651Z","etag":null,"topics":["ai-agents","cli","rust","workflowy"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dhanesh.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-03T21:37:09.000Z","updated_at":"2026-04-03T22:01:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dhanesh/workflowy_cli","commit_stats":null,"previous_names":["dhanesh/workflowy_cli"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/dhanesh/workflowy_cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhanesh%2Fworkflowy_cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhanesh%2Fworkflowy_cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhanesh%2Fworkflowy_cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhanesh%2Fworkflowy_cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dhanesh","download_url":"https://codeload.github.com/dhanesh/workflowy_cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhanesh%2Fworkflowy_cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31691816,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-11T13:07:20.380Z","status":"ssl_error","status_checked_at":"2026-04-11T13:06:47.903Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","cli","rust","workflowy"],"created_at":"2026-04-11T19:12:27.225Z","updated_at":"2026-04-11T19:12:27.878Z","avatar_url":"https://github.com/dhanesh.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# workflowy-cli\n\nToken-efficient Workflowy CLI designed for AI agents. Replaces MCP with a single binary that produces compact JSON output optimized for LLM context windows.\n\n## Quick Start\n\n```bash\n# Build\ncargo build --release\n\n# Set your API key (get one at https://beta.workflowy.com/api-key)\nexport WORKFLOWY_API_KEY=\"your-key-here\"\n\n# Or use interactive setup (writes ~/.config/workflowy-cli/config.toml)\nworkflowy-cli setup\n\n# List your targets (home, inbox, etc.)\nworkflowy-cli targets list\n\n# List nodes under inbox\nworkflowy-cli nodes list --parent inbox\n```\n\n## Installation\n\n### One-liner (recommended)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/dhanesh/workflowy_cli/main/install.sh | bash\n```\n\nOr with a custom install directory:\n\n```bash\nINSTALL_DIR=~/.local/bin curl -fsSL https://raw.githubusercontent.com/dhanesh/workflowy_cli/main/install.sh | bash\n```\n\n### From source\n\nRequires [Rust](https://rustup.rs/) 1.70+.\n\n```bash\ngit clone https://github.com/dhanesh/workflowy_cli.git \u0026\u0026 cd workflowy_cli\nmake build\nmake install   # copies to /usr/local/bin/\n```\n\n## Authentication\n\nAPI key is loaded in this order (first found wins):\n\n1. `WORKFLOWY_API_KEY` environment variable\n2. `~/.config/workflowy-cli/config.toml`\n\nThe config file is created with `600` permissions (owner-only). API keys are never accepted as CLI arguments and never appear in output.\n\n### Interactive Setup\n\n```bash\n# Terminal: masked password prompt\nworkflowy-cli setup\n\n# Piped (for scripts/agents):\necho \"$KEY\" | workflowy-cli setup\n```\n\nSetup validates the key against the API before saving.\n\n## Commands\n\nAll commands follow `workflowy-cli \u003cresource\u003e \u003caction\u003e [args]`.\n\n### Nodes\n\n```bash\n# List children of a parent (default: top-level)\nworkflowy-cli nodes list --parent \u003cid|target|None\u003e\n\n# Create a node\nworkflowy-cli nodes create --parent inbox --name \"Buy milk\" --note \"2%\" --layout todo\n\n# Get a single node\nworkflowy-cli nodes get \u003cuuid\u003e\n\n# Update a node\nworkflowy-cli nodes update \u003cuuid\u003e --name \"New title\" --note \"Updated note\"\n\n# Delete a node\nworkflowy-cli nodes delete \u003cuuid\u003e\n\n# Move a node\nworkflowy-cli nodes move \u003cuuid\u003e --parent home --position top\n\n# Complete / uncomplete\nworkflowy-cli nodes complete \u003cuuid\u003e\nworkflowy-cli nodes uncomplete \u003cuuid\u003e\n\n# Export all nodes as flat list (rate limited: 1 req/min)\nworkflowy-cli nodes export\n```\n\n### Targets\n\n```bash\n# List available targets (home, inbox, shortcuts, etc.)\nworkflowy-cli targets list\n```\n\n### Prime (Agent Onboarding)\n\n```bash\n# Compact manifest (~300 tokens) - for context-constrained agents\nworkflowy-cli prime\n\n# Full manifest (~800 tokens) - complete command reference\nworkflowy-cli prime --full\n```\n\nAgents should call `prime` once at the start of a session to learn all available commands.\n\n## Global Flags\n\n| Flag | Description |\n|------|-------------|\n| `--fields \u003cf1,f2,...\u003e` | Only include specified fields in output (e.g. `--fields id,name,priority`) |\n\n## Output\n\n- **stdout**: Compact JSON (minified, shortened keys). All machine-readable data goes here.\n- **stderr**: Human diagnostics (progress, warnings, retry notices).\n\nThis means `workflowy-cli nodes list | jq .` works without pollution.\n\n### Shortened Keys\n\nOutput uses abbreviated field names for token efficiency:\n\n| Output Key | API Key |\n|------------|---------|\n| `created` | `createdAt` |\n| `modified` | `modifiedAt` |\n| `layout` | `layoutMode` |\n| `done` | `completed` (boolean, export only) |\n\n### Field Filtering\n\nReduce output size for large exports:\n\n```bash\n# Only get IDs and names\nworkflowy-cli nodes export --fields id,name\n\n# Get task-relevant fields\nworkflowy-cli nodes list --parent inbox --fields id,name,priority,done\n```\n\n## Exit Codes\n\n| Code | Meaning |\n|------|---------|\n| `0` | Success |\n| `1` | User/input error (bad arguments, missing required fields) |\n| `2` | API/network error (timeout, server error, rate limit exhausted) |\n| `3` | Authentication error (missing or invalid API key) |\n\n## Error Format\n\nErrors are returned as JSON on stdout for agent consumption:\n\n```json\n{\"error\":\"auth_error\",\"message\":\"No API key found\",\"hint\":\"Set WORKFLOWY_API_KEY env var or run 'workflowy-cli setup'\"}\n```\n\nHuman-readable errors also go to stderr.\n\n## Rate Limiting\n\nThe CLI handles HTTP 429 responses automatically with exponential backoff:\n\n- **Export endpoint**: 60s base delay (respects 1 req/min limit)\n- **All other endpoints**: 2s base delay\n- **Max retries**: 3\n- Retry progress is reported on stderr\n\n## Development\n\n```bash\nmake build          # cargo build --release\nmake test           # cargo test\nmake install        # copy binary to /usr/local/bin/\nmake update-api-docs  # fetch latest API reference from Workflowy\nmake clean          # cargo clean\n```\n\n### API Reference\n\nThe file `workflowy_api.md` contains the Workflowy API reference fetched via [Jina Reader](https://jina.ai/reader/). Update it with:\n\n```bash\nmake update-api-docs\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhanesh%2Fworkflowy_cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdhanesh%2Fworkflowy_cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhanesh%2Fworkflowy_cli/lists"}