@doist/automations-cli 0.0.0 → 1.1.0

package/README.md

@@ -1,45 +1,400 @@
-# @doist/automations-cli
+# `tda`
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+Terminal client for Todoist Automations. It can inspect and manage automations, drafts,
+conversations, and runs, and it uses the same persisted agent conversations and client-managed tools
+as the Automations frontend.
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+The agent can create and edit automations, inspect existing automations and runs, troubleshoot
+failures, and answer other automation-related questions. The CLI sends the initial message unchanged;
+it does not assume that every conversation is an authoring request.
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+## Installing
 
-## Purpose
+```bash
+npm install -g @doist/automations-cli@internal
+```
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@doist/automations-cli`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+The `@internal` part is required. Releases are published under that dist tag and no other, so the
+usual `npm install -g @doist/automations-cli` finds no version to install for as long as Automations
+is invite-only.
 
-## What is OIDC Trusted Publishing?
+Once installed, upgrade with `tda update`, or `tda update --check` to see what is available without
+installing anything. It installs from the same `internal` tag, so there is no release channel to
+choose. Re-running the install command above works just as well.
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+Signing in still needs an account with Automations access, so installing the CLI on its own grants
+nothing.
 
-## Setup Instructions
+## Local development
 
-To properly configure OIDC trusted publishing for this package:
+From the monorepo root, install dependencies and create the global link once:
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+```bash
+npm install
+npm run setup:cli
+```
 
-## DO NOT USE THIS PACKAGE
+This builds the shared workspace packages and CLI, then creates an npm link for the `tda` executable.
+The link is persistent. After editing `apps/cli/src`, rebuild only the CLI:
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+```bash
+npm run build:cli
+```
 
-## More Information
+For active development, keep the bundler running instead:
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+```bash
+npm run dev:cli
+```
 
----
+Both commands update the linked executable without recreating the link. A linked build reports its
+version as `0.0.0-development`, since the real number is written at publish time, so
+`tda update --check` always claims an update is available; rebuild the link rather than running
+`tda update`, which would replace it with a global install. Run `npm run build:core`
+after editing a shared package. Run `npm unlink --global @doist/automations-cli` to remove the link.
 
-**Maintained for OIDC setup purposes only**
+A global install and a link cannot both own `tda`, so uninstall the published package first if you
+have one.
+
+## Releases
+
+`@doist/automations-cli` is published from `main` by
+[`.github/workflows/release-cli.yml`](../../.github/workflows/release-cli.yml), which runs
+semantic-release with the configuration in [`release.config.js`](./release.config.js). The version
+comes from the conventional-commit messages that touched this directory, so nothing has to be bumped
+by hand and the repository holds no version number of its own.
+
+The workspace libraries the CLI uses are not published, so `npm run build` compiles them into
+`dist/` rather than resolving them at install time. Only the packages listed under `dependencies`
+are left external. Because a release is scoped to commits under `apps/cli`, a change confined to one
+of those libraries does not trigger a release even though it changes what gets published; it ships
+with the next release instead. Publish it sooner by landing it together with a change here.
+
+Once linked, `tda skill install claude-code` gives your coding agent instructions for driving the
+CLI. See [Agent skill](#agent-skill).
+
+## Authentication
+
+Sign in with your Todoist account:
+
+```bash
+tda auth login
+```
+
+This opens a browser, asks Todoist to authorize the CLI, and stores the resulting token in your
+operating system credential manager. `tda auth status` shows which account is signed in, and
+`tda auth logout` removes the credential and tells Todoist to revoke it.
+
+The token is minted for Automations specifically rather than for Todoist as a whole, so it grants
+access to your automations and not to your tasks, projects or comments. The one exception is your
+identity: signing in also asks for Todoist's `user:read` scope and reads your account id and email,
+which is how the CLI knows who it stored the credential for. It lasts an hour and is renewed
+automatically as commands run, so signing in is a one-off.
+
+### Scopes
+
+By default the CLI asks for write access to automations, connections and chat, plus permission to
+run automations. `--read-only` asks for read access instead, which leaves `automation trigger`,
+`chat`, and every connector change failing with a permissions error.
+
+```bash
+tda auth login --read-only
+```
+
+Scopes that no command needs yet — workspaces, notifications, settings and webhooks — are not
+requested by default. Ask for them up front if you want them, rather than signing in a second time
+later:
+
+```bash
+tda auth login --additional-scopes workspaces,notifications,webhooks
+```
+
+`workspaces` covers automations that live in a Todoist workspace rather than your personal space.
+They are a separate resource with their own scopes, because a workspace holds other people's
+automations too.
+
+`tda auth login --help` lists them with what each one covers.
+
+### Environments
+
+`--env` selects which Automations deployment to talk to, and the account you sign in as is stored
+per environment, so a staging login never leaks into a production command:
+
+```bash
+tda --env staging auth login
+tda --env staging automation list
+```
+
+`prod` is the default. `TDA_ENV` sets it for a shell session. `--api-url` (or `TDA_API_URL`)
+overrides just the API address, for a proxy or a local backend, and takes precedence over `--env`.
+
+Signing in against `dev` needs the local backend running with `APP_URL=https://local-agentist.todoist.com`.
+On its default of `http://localhost:24368`, Todoist cannot fetch the document that identifies the
+CLI, so the login fails.
+
+### Personal API tokens
+
+A Todoist personal API token still works, and takes over when no account is signed in:
+
+```bash
+export TODOIST_API_TOKEN="<your Todoist personal API token>"
+```
+
+A signed-in account wins over the variable, so logging in does not require unsetting it. The
+variable is useful for CI and scripts, where opening a browser is not an option.
+
+### Where the credential is stored
+
+By default, only in your operating system credential manager. On a machine without one — a
+container, a headless host, some WSL setups — login fails rather than quietly writing the token to
+a file. Use `--credential-store` to choose deliberately:
+
+```bash
+tda auth login --credential-store fallback   # keyring if available, config file if not
+tda auth login --credential-store plaintext  # config file, always
+```
+
+`plaintext` always writes the token to `~/.config/tda/config.json`; `fallback` does so only when no
+keyring is available, and otherwise behaves like the default. That file is readable by anything
+running as you, so it is worth knowing which one you get. It is created `0600`.
+
+### Known limitation
+
+A `tda chat` turn starts with at least ten minutes of token life, which covers any normal turn. A
+turn running longer than that fails partway through, because the connection carries the token it
+opened with. Re-run `tda chat continue` to resume. Fixing this properly means the SDK resolving the
+token per request rather than holding the one it was built with.
+
+## Inspecting resources
+
+Every resource has `list` and `view` commands. Use `--json` for complete machine-readable output:
+
+```bash
+tda --json automation list --all
+tda --json automation view <automation-id>
+
+tda --json draft list --all
+tda --json draft view <draft-id>
+
+tda --json conversation list --status all --limit 200
+tda --json conversation view <conversation-id>
+
+tda --json run list <automation-id> --status failed --all
+tda --json run list <automation-id> --status failed --since 2026-08-01 --until 2026-08-07
+tda --json run view <automation-id> <run-id>
+tda --json run view <automation-id> <run-id> --full
+```
+
+Automation, draft, and run lists support `--limit`, `--cursor`, and `--all`. `--limit` controls the
+total number of returned resources; `--all` removes that limit. JSON responses retain the API's
+`data` and `nextCursor` fields. NDJSON emits one resource per line and adds a final
+`{"_meta":true,"nextCursor":"..."}` record when another page is available.
+
+`run list` filters on when a run was created. `--since` and `--until` each take a full ISO timestamp
+(`2026-08-01T09:00:00Z`) or a plain `YYYY-MM-DD` date, and both bounds are inclusive: a plain date
+covers that entire UTC day, so `--since 2026-08-01 --until 2026-08-07` returns everything from the
+start of the 1st to the end of the 7th. Either bound can be used on its own; with only `--since`,
+the range runs up to now.
+
+`conversation view` returns the persisted conversation and its raw messages. `chat status` remains
+focused on resumable agent state, including pending client actions.
+
+To investigate a failing automation, an agent can list automations, inspect the selected automation,
+list its failed runs, and inspect one failed run. Run details default to a compact diagnostic view
+with failure, step, and tool-call errors. Use `run view --full` when raw step results and tool payloads
+are needed.
+
+## Managing automations
+
+Enable or disable an automation, or start a live run:
+
+```bash
+tda automation enable <automation-id>
+tda automation disable <automation-id>
+tda automation trigger <automation-id>
+```
+
+`automation trigger` only supports scheduled automations. It starts a live run and exits after the
+backend accepts it; it does not wait for the run to finish. API triggers are not supported because
+the command cannot provide their input payload. Webhook automations run through their configured
+event.
+
+Replace an automation's name and description together:
+
+```bash
+tda automation update <automation-id> \
+  --name "Daily summary" \
+  --description "Creates a morning summary"
+```
+
+Replace its schedule with either an interval or a five-part cron expression:
+
+```bash
+tda automation schedule <automation-id> --interval "45m"
+
+tda automation schedule <automation-id> \
+  --cron "0 9 * * *" \
+  --timezone "America/Santiago"
+```
+
+Cron schedules require an IANA timezone. `--cron` and `--interval` are mutually exclusive, and
+natural-language values such as `every day at 9am` are not supported.
+
+These explicit mutation commands do not prompt for confirmation and do not support `--dry-run`.
+Use the global `--json` or `--ndjson` option for structured results.
+
+## Conversations
+
+```bash
+tda --ndjson chat start \
+  "Why did my daily summary automation fail yesterday?"
+
+tda --ndjson chat continue <conversation-id> \
+  "Inspect its most recent run"
+
+tda --json chat status <conversation-id>
+```
+
+Creating an automation is another kind of conversation. State the desired publication behavior in
+the message:
+
+```bash
+tda chat start "Create and publish an automation that reschedules overdue tasks every night"
+
+tda chat start \
+  "Create an automation that reschedules overdue tasks every night, but leave it as a draft"
+```
+
+The CLI does not add publication or draft instructions to these messages.
+
+## Agent usage
+
+The CLI streams one durable server turn and exits. In NDJSON mode, `turn_started` means the process is
+still active, and silence produces periodic `turn_progress` heartbeats. Keep monitoring the same
+process until both of these are true:
+
+1. It emits `turn_completed` with `terminal: true`.
+2. The process exits.
+
+Only then should an agent invoke `tda chat continue` with the emitted conversation ID. A local
+per-conversation lock rejects a concurrent turn and reports the PID that is already active. The lock
+protects processes on the same machine; it is not a distributed backend lock.
+
+In a human terminal without `--json`, `--ndjson`, or `--no-interactive`, the command remains open as
+an interactive conversation.
+
+```ndjson
+{"type":"turn_started","conversationId":"...","state":"running","terminal":false}
+{"type":"turn_progress","conversationId":"...","state":"running","terminal":false,"elapsedSeconds":30}
+{"type":"turn_completed","conversationId":"...","state":"completed","terminal":true,"outcome":"awaiting_input","resumeCommand":"tda chat continue ..."}
+```
+
+If a conversation publishes an automation, `tda` archives the conversation before emitting the
+terminal `turn_completed` event. Successful machine output includes `conversation_archived` and
+`conversationArchived: true`. If publication succeeds but archival fails, the CLI emits a
+`TDA_CHAT_ARCHIVE_FAILED` warning and completes with `conversationArchived: false`; agents must not
+retry publication in response to that warning.
+
+## Connections
+
+Discover every service supported by Automations and include the current user's connection status:
+
+```bash
+tda connector list
+tda connector list --query github
+tda connector list --capability mcp
+tda connector list --connection-status authorized
+tda connector list --capability trigger --connection-status expired
+tda connector list --without-connections
+tda connector list --no-connections
+tda connector view github
+```
+
+`--capability` filters connectors by what they support but does not remove other capabilities or
+connections from the output. When combined with `--connection-status`, both conditions must match
+the same connection. `--without-connections` returns only connectors for which the user has no
+connection records. `--no-connections` skips fetching connection data and omits the `connections`
+field; it cannot be combined with connection filters.
+
+List the published automations that require a connector:
+
+```bash
+tda connector automations github
+```
+
+Start a connection directly, or resume and repair an existing setup:
+
+```bash
+tda connector connect github --capability mcp
+tda connector wait <connection-id>
+tda connector repair <connection-id>
+```
+
+OAuth setup opens in the default browser. Managed connectors print their instructions and setup
+code. Use the global `--no-open` option to print setup links without opening them.
+
+Disconnecting is preview-only unless `--yes` is present. The CLI refuses to disconnect an exact
+connection used by any enabled automation. Disabled automations do not block disconnection, but they
+will need a valid connection before they can run again.
+
+```bash
+tda connector disconnect <connection-id>
+tda connector disconnect <connection-id> --yes
+```
+
+The dependency check currently runs in the CLI before deletion and is not atomic with the backend
+operation. Backend enforcement is tracked in
+[#3928](https://github.com/Doist/automations/issues/3928).
+
+### Connections requested by chat
+
+The backend and CLI automatically reuse the sole authorized account for a requested service. When
+more than one authorized account exists, machine mode emits an `action_required` event containing
+the available connection IDs. Resolve it with:
+
+```bash
+tda --ndjson chat continue <conversation-id> \
+  --connection slack:mcp=<connection-id>
+```
+
+Repeat `--connection` when several service choices are required.
+
+When no authorized account exists, the CLI creates a connection and waits for setup to complete. For
+OAuth connectors it prints the authorization URL and opens it in the default browser. For managed
+connectors it prints the setup instructions and code, and opens the deep link when one is available.
+Machine mode emits `connection_authorization_started`, periodic
+`connection_authorization_waiting`, and `connection_authorized` events while the same process stays
+alive. Pending setup is reused if the command is interrupted and resumed, avoiding duplicate
+connections.
+
+Use `--no-open` to print OAuth and managed deep-link URLs without trying to launch a browser:
+
+```bash
+tda --no-open --ndjson chat start "Help me troubleshoot my Slack automation"
+```
+
+## Agent skill
+
+`tda` ships a skill document that teaches a coding agent how to drive it: which command answers which
+question, what each flag really does, the chat turn protocol, and the error codes worth branching on.
+Install it for whichever agents you use:
+
+```bash
+tda skill install claude-code          # writes ~/.claude/skills/automations-cli/SKILL.md
+tda skill install claude-code --local  # writes ./.claude/skills/automations-cli/SKILL.md
+tda skill list
+tda skill update all
+tda skill uninstall claude-code
+```
+
+`tda skill list` shows every supported agent (`claude-code`, `codex`, `copilot`, `cursor`, `gemini`,
+`pi`, and `universal` for `~/.agents`) along with whether its skill file is missing, current, or
+outdated. A global install refuses when the agent's home directory does not exist, so a typo cannot
+create a directory nothing reads; use `--local` or the `universal` target instead. Already-installed
+skill files are rewritten by `npm run build:cli`, which is when the document can change, so a rebuilt
+CLI never leaves an agent reading instructions that no longer match it. `tda skill update all` does
+the same on demand.
+
+The document's source is `src/lib/skills/content.ts`, and `skills/automations-cli/SKILL.md` is the
+generated copy committed for review. Edit the former and run `npm run sync:skill`; `npm run check`
+fails when they diverge.