Echoic CLI

The echoic command gives people and software agents a first-party terminal interface for Echoic brand setup, campaigns, content generation, publishing, usage, and account status.

Requirements

• Node.js 22.13 or newer
• An Echoic account and workspace

Install

Install the public package globally:

npm install --global @symphco/echoic
echoic --help

To test a package tarball before publication:

npm install --global ./symphco-echoic-0.2.0.tgz
echoic --help

The installed command is always echoic.

Sign In

Check for an existing session before starting a browser flow:

echoic session status
echoic login
echoic whoami
echoic workspaces list

echoic login uses Echoic's browser handoff and opens the verification page by default. Agents should ask the user before starting login, then keep the terminal running until it confirms that the local session was stored. When a browser cannot be opened, use echoic --no-browser login to print the URL and verification code for the user. Closing the browser tab does not cancel the request; press Ctrl+C in the terminal to cancel it. Browser approval alone does not create a local CLI session.

The CLI stores the workspace-scoped bearer token only in the operating system credential store. If that store is unavailable, login stops without writing a plaintext token file. Set up Windows Credential Manager, macOS Keychain, or a Linux Secret Service-compatible store, then rerun echoic login. Do not request, print, or persist the full token.

For scriptable or headless login, run echoic login --json and retain its single verification response, including resumeCommand; then run echoic login complete --json for the final session response. Use echoic session list, echoic session revoke <session-id>, or echoic session revoke-all --yes to manage remote sessions. A normal echoic logout revokes the current remote session before deleting local state. If the service is unavailable, it preserves the local credential and tells you to use the explicit echoic logout --local-only --yes fallback.

Agent Discovery

Agents should discover the installed command surface instead of guessing syntax:

echoic commands --json
echoic help agents
echoic help json

Use --json for reads, status checks, and command chaining. JSON output is stable, non-animated, and owned by the CLI. Human output can show prompts and progress for long-running work.

Invalid invocations are actionable rather than generic. They leave stdout empty, write a safe diagnostic to stderr, and exit 2. For example, echoic brand list --limt reports the scoped command, suggests --limit, and gives echoic brand list --help as the next command. --json emits the equivalent single error object on stderr. --help and --version remain normal text output; use echoic commands --json for machine-readable discovery.

Human output renders dates and timestamps in a readable form; timestamps use the local machine timezone and name that timezone. JSON preserves the original API date and timestamp strings for agents and automation.

Before mutating, bulk, AI-generation, platform OAuth, or publishing actions, inspect the command manifest and obtain any user confirmation it declares. Use --yes only after the user approves the exact action.

Common Workflow

echoic session status
echoic --json workspaces list
echoic workspaces use <workspace-id>
echoic brand setup --url <brand-url> --brand-name <name>
echoic brand next <session-id>
echoic brand answer <session-id> --field <question-id> --value "..."
echoic brand review <session-id>
echoic brand generate --session <session-id> --yes
echoic brand readiness <brand-id>
echoic brand complete <brand-id>
echoic brand strategy fields
echoic --json brand strategy show <brand-id>
echoic brand strategy update <brand-id> --field positioning --json-value '["AI product partner"]'
echoic --json brand strategy show <brand-id>
echoic campaign setup --brand <brand-id>
echoic campaign next <session-id>
echoic campaign answer <session-id> --field <question-id> --value "..."
echoic campaign review <session-id>
echoic campaign create --session <session-id> --start-date 2026-08-01 --days 14 --timezone Asia/Manila --yes
echoic campaign status <campaign-id>
echoic posts list --campaign <campaign-id>
echoic posts show <post-id> --full
echoic usage summary

Long-running human-output commands wait and show progress by default. Use --no-wait only when the caller intends to start background work and check it later with echoic jobs commands. Async JSON responses include started, waited, job, and nextCommand.

Campaign duration is set when creating the campaign: use --days <1-90> (default: 30) with optional --name, --start-date YYYY-MM-DD, and --timezone <IANA name> on either the guided --session path or the fast --brand/--brief path. Platforms are required: guided intake answers preferredPlatforms, while the fast path passes --platforms facebook. Campaign platforms guide content generation and do not require a publishing connection until publish time.

Do not mix guided and fast campaign flags. Guided answers and brand answers accept exactly one of --value, --json-value, or --decide-for-me.

For guided brand and campaign sessions, every API-returned question is required by the CLI. Run brand next or campaign next first, answer only that question, wait for success, then follow the returned nextCommand. Use questions for the full annotated list. Guided generation and guided campaign creation refuse incomplete sessions and identify the missing question IDs. Use --refresh after answers or materials change through the web app or another client. Before campaign setup, use echoic brand readiness <brand-id>; brands require completed review plus complete identity and content, while other profile sections remain quality warnings.

Generation may spend credits. Obtain approval and pass --yes; --no-wait does not approve spending. For the smallest explicit visual request, use echoic posts generate-visuals <post-id> --slides 1 --yes. Use --from-file <path> for advanced visual options (slides, style, backgroundMode, and imageModel).

posts show --full, posts media, posts generate-visuals, and posts generate-creative return safe media summaries plus the canonical Echoic /content/<post-id> review page. They never expose direct image, CDN, storage, or signed URLs.

Paginated lists return nextCursor. Continue with --cursor for brand list, campaign list, jobs list, publish history, and billing invoices.

Brand strategy updates merge with existing guidance and preserve omitted fields. Discover the accepted fields with echoic brand strategy fields, inspect before and after with echoic --json brand strategy show <brand-id>, and prefer --from-file for complex JSON. brand strategy replace removes omitted fields and requires explicit confirmation.

Use echoic usage summary for product-facing credits, generation access, and publishing allowance. echoic usage credits adds a compact billing breakdown; use echoic billing subscription and echoic billing invoices for detailed subscription state and local Echoic history. A TRIALING plan is shown as Free Trial and uses real plan credits, not legacy trial caps. Billing history is not a provider receipt download. echoic billing cancel requires confirmation and reports the actual provider-backed result; it immediately ends a trial and may report immediate paid cancellation if period-end cancellation is unavailable. echoic usage activity reports safe aggregate request counts only; it does not expose provider/model telemetry or raw failures.

echoic --json brand fields returns the legacy fields array plus typed definitions with JSON types, nullability, clearability, descriptions, and examples. Platform connect/disconnect/check values are facebook, instagram, linkedin, and tiktok; connection diagnostics are implemented for Facebook/Meta and LinkedIn, while Instagram and TikTok return not_implemented.

TypeScript consumers can import manifest-referenced output types, including CliBrandFieldsOutput, directly from @symphco/echoic.

API Endpoint

The default API endpoint is:

https://echoic-api.symph.ai/api

Override it for one command with --api-url or for a process with ECHOIC_API_URL:

echoic --api-url https://example-api.company.test/api session status

Only use an endpoint the user or organization trusts. The CLI rejects non-HTTPS remote URLs; HTTP is accepted only for localhost development.

Update And Remove

npm update --global @symphco/echoic
npm uninstall --global @symphco/echoic

Uninstalling the package does not intentionally reveal or print stored credentials. Run echoic logout before uninstalling when the local Echoic session should also be removed.

Troubleshooting

• Run node --version and confirm it is at least 22.13.
• Run echoic session status to inspect the API URL, selected workspace, expiry, and masked token preview.
• Run echoic commands --json to confirm the installed command manifest is available and parseable.
• Use echoic --no-browser login when the terminal cannot launch a browser.
• Reinstall the package if echoic is not on the shell's global npm binary path.

Report package or command problems through the Echoic issue tracker.

License

The Echoic CLI package and its bundled internal runtime packages are distributed under the Apache License 2.0. See LICENSE in the installed package.