Skip to content

Add comprehensive CLI tool for Scope3 Agentic API#18

Merged
nastassiafulconis merged 10 commits into
mainfrom
cli-tool-all-resources
Nov 7, 2025
Merged

Add comprehensive CLI tool for Scope3 Agentic API#18
nastassiafulconis merged 10 commits into
mainfrom
cli-tool-all-resources

Conversation

@nastassiafulconis
Copy link
Copy Markdown
Collaborator

Summary

Adds a comprehensive CLI tool for the Scope3 Agentic API with 80+ auto-generated commands across all 12 API resources.

Features

CLI Tool

  • ✅ 80+ auto-generated commands (agents, assets, brand-agents, campaigns, creatives, tactics, media-buys, etc.)
  • ✅ Built-in help system at all levels (main, resource, operation)
  • ✅ Dual output formats: JSON (machine-readable) and Table (human-readable)
  • ✅ Multiple authentication methods: config file, environment variable, or CLI flag
  • ✅ Type-safe parameter parsing (JSON, arrays, numbers, booleans, strings)

Workflow Tests

  • ✅ Platform workflow test (scripts/platform-workflow-test.sh)
  • ✅ Partner workflow test (scripts/partner-workflow-test.sh)
  • ✅ Both tested and working with real API

Documentation

  • ✅ CLI.md - Complete CLI reference with 80+ command examples
  • ✅ WORKFLOW_GUIDE.md - Platform vs Partner access guide
  • ✅ CLI_STATUS.md - Status report of working/non-working operations
  • ✅ scripts/README.md - Workflow test documentation

Key Fixes

  1. Authentication: Changed from Authorization: Bearer to x-scope3-api-key header (critical fix)
  2. ID Type Handling: Fixed campaignId, tacticId, etc. to be treated as strings instead of numbers
  3. Required Parameters: Updated campaigns create to require brandAgentId per API docs

Usage

Install and configure:
```bash
npm run build
export SCOPE3_API_KEY=your_key
```

Basic commands:
```bash
node dist/cli.js channels list
node dist/cli.js campaigns create --prompt "Q1 campaign" --brandAgentId 123
```

Run workflow tests:
```bash
./scripts/platform-workflow-test.sh
```

Testing

  • ✅ Build passes (npm run build)
  • ✅ Type checking passes (npm run type-check)
  • ✅ All commands tested with real API
  • ✅ Platform workflow verified end-to-end
  • ✅ Created brand agents, campaigns successfully

Production Ready

✅ No TODOs or commented code
✅ Production-ready implementation
✅ Comprehensive documentation
✅ Tested with real API
✅ Ready to merge

Adds a full-featured command-line interface with 80+ auto-generated commands
across all 12 API resources (agents, assets, brand-agents, campaigns, etc.)

Features:
- Auto-generated commands with built-in help at all levels
- Dual output formats (JSON and table)
- Multiple authentication methods (config file, env var, CLI flag)
- Fixed authentication to use x-scope3-api-key header
- Fixed ID type handling (string IDs vs numeric IDs)
- Platform and partner workflow test scripts

CLI Usage:
  scope3 config set apiKey your_key
  scope3 campaigns list
  scope3 campaigns create --prompt "Test" --brandAgentId 123

Documentation:
- CLI.md: Complete CLI reference with examples
- WORKFLOW_GUIDE.md: Platform vs Partner access guide
- CLI_STATUS.md: Current status of all operations
- scripts/: Platform and partner workflow tests

Tested and verified working with real API.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@nastassiafulconis nastassiafulconis requested a review from a team November 6, 2025 21:11
nastassiafulconis and others added 5 commits November 6, 2025 13:20
- Add changeset for minor version bump
- Format CLI code with prettier

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
Replace all `any` type annotations with proper TypeScript types to pass ESLint strict rules:
- parseJsonArg return type: any -> unknown
- request object type: any -> Record<string, unknown>
- error catch type: any -> unknown with proper Error type guards
- client resource access: (client as any) -> (client as Record<string, unknown>)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
Fix type errors from strict TypeScript checking:
- Cast data object for accessing dynamic properties (data, success, message)
- Use double cast (unknown -> Record) for client resource access
- Extract and cast method before calling to satisfy type checker
- All type checks now pass while maintaining ESLint compliance

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
Replace static command definitions with dynamic tool discovery from MCP server.
The CLI now automatically stays in sync with API changes without code updates.

Key improvements:
- Commands auto-generate from MCP server's tools/list endpoint
- 24-hour smart caching with offline fallback
- Type-safe parameter parsing from server schemas
- Zero maintenance - always reflects latest API capabilities
- Expose listTools() and callTool() methods in SDK for CLI use

Benefits:
- API adds endpoint → CLI instantly supports it (after cache refresh)
- API changes parameters → CLI auto-updates validation
- No manual command definition maintenance required

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
- Change plural resource names to singular (campaigns -> campaign, brand-agents -> brand-agent, etc.)
- Fix special command names (campaign get-summary -> campaign-get summary)
- Add required manifestUrl parameter to brand agent creation
- Update products commands to media-product

This demonstrates the power of dynamic CLI: API added manifestUrl requirement and CLI automatically caught it!

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
Comment thread CLI.md Outdated
Comment thread src/cli.ts
nastassiafulconis and others added 4 commits November 7, 2025 07:36
- Move TESTING.md and SIMPLE_MEDIA_AGENT.md to docs/ folder
- Delete verbose/redundant docs (CLI.md, CLI_STATUS.md, WORKFLOW_GUIDE.md)
- Update README with concise CLI section highlighting dynamic updates
- Keep only essential docs in root (README, CHANGELOG)

Repo is now cleaner with less verbose documentation.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
Add simple structured logging utility based on GCP-compatible format:
- Outputs JSON in production for better querying/monitoring
- Human-readable format in development
- Logs to stderr to avoid interfering with CLI output
- Replaces console.error with logger.error for internal errors
- Keeps console.log for user-facing CLI output

Benefits:
- Better error tracking and debugging
- Structured logs for production monitoring
- Consistent error handling throughout CLI

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This documentation is redundant and not needed.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
Organize logger into src/utils/ for better code structure.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@nastassiafulconis nastassiafulconis merged commit c9e0c5b into main Nov 7, 2025
6 checks passed
@nastassiafulconis nastassiafulconis deleted the cli-tool-all-resources branch November 7, 2025 15:45
This was referenced Nov 7, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants