Trello Task Board
Use
; do not construct Trello HTTP requests yourself. On first use, run
cyeam trello login --key <api-key>
, authorize in the browser, and paste the Token displayed on the page back into the CLI. The CLI validates the token and stores it in the system keychain. If the keychain is unavailable, it falls back to
with permissions
. Never output credentials.
Rules
- If you do not know an ID, run first and then ; do not guess IDs from names.
- To query today's tasks, use
cards --board <board-id> --today
; filtering is based on the local time zone and .
- Creating, modifying, moving, uploading attachments, and adding or removing Webhooks change external state, so you must obtain the user's explicit confirmation first.
- Webhook commands only manage subscriptions; the public HTTPS receiving endpoint, signature verification, deduplication, and Android synchronization are implemented by a separate service.
- The and environment variables are only for CI or temporary overrides; if either one is set, the other must be set as well.
Commands
text
cyeam trello login --key <api-key>
cyeam trello status
cyeam trello logout
cyeam trello boards
cyeam trello lists <board-id>
cyeam trello cards --list <list-id> [--today]
cyeam trello cards --board <board-id> [--today]
cyeam trello status-changes --board <board-id>
[--date <YYYY-MM-DD>] [--to-list <list-id>] [--limit 1000]
cyeam trello homework --board <board-id>
[--date <YYYY-MM-DD> | --from <YYYY-MM-DD> --to <YYYY-MM-DD>]
[--include-actions] [--audio-only] [--asr] [--dir <目录>]
[--max-width 1200] [--max-bytes <bytes>]
cyeam trello card create --list <list-id> --name <title>
[--desc <text>] [--due <RFC3339>] [--labels <label-id,...>]
[--requirements <text>]
[--type normal|word_memorization|english_reading|arithmetic|preview] [--task <text>]
[--link <url>] [--word <word-or-phrase> ...]
cyeam trello card update <card-id>
[--name <title>] [--desc <text>] [--due <RFC3339>] [--complete=true|false]
cyeam trello card move <card-id> --list <target-list-id>
cyeam trello card attach <card-id> --file <local-path> [--name <display-name>]
cyeam trello card attachments <card-id>
cyeam trello card attachment get <card-id> <attachment-id>
[--out <local-path>] [--max-width <px>] [--max-bytes <bytes>]
cyeam trello card actions <card-id> [--limit 50]
cyeam trello webhook create --callback-url <https-url> --model-id <id>
[--description <text>]
cyeam trello webhook delete <webhook-id>
clears the due date; if
is omitted, the task's completion status is unchanged. The default output is a JSON envelope;
outputs the response as pretty-printed JSON.
When creating a homework card,
defaults to
, preserving the behavior of previously passing
directly.
--type word_memorization --task "bedroom, armchair"
writes only the homework type and word list to the description;
--type english_reading --task "/ai/translate?textbook=0&article=4"
writes the user-provided link to the description verbatim. Create only one card per task.
When passing an already ordered vocabulary list for a word-memorization assignment, repeat
once for each item, for example
--type word_memorization --word "bus stop" --word "train station" --word "airport"
. The word list retains this order, and each phrase is one item.
and
are mutually exclusive. The homework flow organizes the word list by meaning, topic, and spelling before creating the assignment.
When the user provides homework requirements for highlighting and reading aloud on a tablet, use
--requirements "写清题号,做完检查一遍。"
. The CLI writes a separate
field in the card description; this applies to all homework types.
For word memorization,
is split only on English or Chinese commas; spaces are part of a phrase. For example,
--task "ice cream, piece of cake"
contains two items. Both
and
are validated against the native Android word-memorization rules: English letters, intra-word apostrophes (
,
), hyphens, and spaces within phrases are supported; English parenthetical continuation words such as
are converted to
, while Chinese parenthetical annotations such as
are removed. Numbers, URLs, other punctuation, and unmatched parentheses cause an error before creation;
for English reading undergoes the same validation. Leading and trailing whitespace and repeated whitespace within a phrase are normalized, while word order and capitalization are preserved.
For English reading, you can pass both a lesson link and a read-aloud vocabulary list, for example
--type english_reading --task "<原始课文链接>" --word "robotics" --word "build our own"
. The CLI writes the
field in the original order.
Normal homework supports
--type normal --task "完成第一课练习" --link "https://实际的作业网址"
(the type also accepts
).
is the homework content, and
is the raw target URL supplied by the user. If the input is a Markdown link, extract the URL inside the parentheses; do not pass the entire Markdown text. Put general instructions in
. The CLI preserves the description and appends:
text
类型: 普通作业
作业内容: 完成第一课练习
作业链接: [https://实际的作业网址](https://实际的作业网址)
When there is no link, omit
and the “作业链接” line from the description.
is only available for normal homework, requires a non-empty
, and cannot contain a newline. Normal homework without
or
still uses
verbatim. When updating existing normal homework, use
to submit the complete description; the update command has no
,
, or
parameters.
Arithmetic homework uses
--type arithmetic --task <多行题目>
(the type also accepts
). Each line of
must contain one problem and must use actual line breaks; do not include a problem-list title, name field, answers, Markdown tables, or multi-column formatting. Put estimated time and similar information in
, for example
. The CLI preserves the description and appends
,
, and the complete problems; the tablet reads the problems and formats them automatically.
bash
cyeam trello card create --list <list-id> --name "口算20题(第N天)" --due <RFC3339> \
--type arithmetic --task '26 + 17 = ___
54 − 28 = ___' --desc '预计用时: 5'
When updating an existing arithmetic card,
still uses
to submit the complete description, including the type, estimated time,
, and all problems. The command has no
or
parameters. Put general instructions before
and only the problems after it.
Preview homework uses
and also accepts
. The CLI appends
and
to the end of the general description. When creating the card,
may be omitted or used to prefill multiline requirements. Parents can save requirements under
on the tablet. When the tablet submits preview results, it writes the saved requirements into this field.
To retrieve images, first use
card attachments <card-id>
to find the
, filename, and MIME type, and then call
. When displaying images in Feishu, prefer passing
: the CLI uses the stored Trello credentials to download the protected attachment and writes the image bytes directly to the file, then returns
,
,
, and
; the Agent then uploads the local file. By default, the original image is downloaded. If the image is too large, add
to download a server-generated preview, which uses WebP and is much smaller. If the original content is already WebP,
is
. Do not parse JSON yourself, decode Base64, or send the protected URL directly to Feishu. Omit
only when the caller explicitly requires inline data; only then does the response contain
. The default attachment limit is 25 MiB.
queries card-list transition records for a given day in the local time zone and defaults to today. It returns the card, the source and destination lists, the actor, and
. When organizing tasks completed each day, you must first use
to find the completed-list ID and then pass
; do not guess the ID from the list name.
To inspect homework progress and submitted attachments for a given day, use the complete command
cyeam trello homework --board <board-id>
. It filters for cards due on that day, returns the list containing each card, and downloads all attachments to a local directory, which defaults to
. This is a
read-only report command; it does not create or append homework. Do not use the nonexistent command
; use
to add homework. By default, it downloads the largest image preview no wider than
(1200); pass
to download the original files. In the JSON report, each attachment includes a
path and a
link in the form
https://trello.com/1/cards/<card-id>/attachments/<attachment-id>/download/<filename>
, which can be opened directly in a browser after logging in to Trello. Built-in timeout retries ensure that a failure on one card does not interrupt the entire report.
Audio attachments are identified by the filename prefix
, using the naming format
homework-audio-{提交ID}-{序号}.{扩展名}
.
lists and downloads recordings like other attachments; to extract only recordings, add
, for example
cyeam trello homework --board <board-id> --from <YYYY-MM-DD> --to <YYYY-MM-DD> --audio-only
. Recordings are stored in the corresponding card's subdirectory under the report directory, with the path available in the attachment's
field; downloading requires valid Trello CLI authorization. During extraction, add
to transcribe audio attachments of all homework types through ASR and return the text directly in each attachment's
field.
also displays the “识别文本”. A failure is written to
, preserves the local audio, and does not interrupt the other attachments. Audio is identified by its recording prefix, MIME type, or extension.
disables all transcription. When
is not explicitly specified, the legacy behavior of automatically transcribing English cards remains in effect; a card qualifies if its title contains
or its type is English reading or word memorization. Use
to disable this behavior. An explicit
setting takes precedence over the legacy parameter. If an old recording or exception has no
in the report, use the asr skill's
command to transcribe it manually; do not construct the recognition request yourself.
The hard rules for extracting images are:
always use the local file when viewing or forwarding an image, open it with an image-reading tool, and confirm its contents before displaying it. The
link is for display only; do not pass it to curl/wget or send it to Feishu, because requests without a browser session will return 401/403. Check every attachment in the report: a non-empty
or a
value of 0 indicates a failed download. Retry it individually with
card attachment get <card-id> <attachment-id> --out <path>
, which downloads the original by default, or use
for a smaller preview image.
A homework summary can use
cyeam trello homework --board <board-id> --from <YYYY-MM-DD> --to <YYYY-MM-DD> --include-actions
to read materials for multiple days in one batch. The start and end dates are inclusive and are mutually exclusive with
; omitting the dates still queries today. The report filters current, unarchived cards by
due date, not by submission time. Cards without a due date and archived cards are excluded. The report adds
,
, and each card's original
.
additionally returns up to the most recent 1000
for each card, including comments; a read failure is written to
and does not block image downloads. If a card has reached 1000 actions, state that the history may have been truncated. Attachment directories include the card ID to avoid confusing assignments with identical names. Refer to the homework skill for the model-grading and review-record workflow; the CLI does not perform grading itself.
Grading Result Fields
When publishing a grading result, pass
and simultaneously write the first line of the card description as
, and publish the current grading comment. Replace an existing field with the same name on the first line only; otherwise, prepend a new line while preserving the original question and other instructions. This approach is compatible with Trello's free plan and does not depend on native custom fields. A score of 100 means that the entire submission is explicitly and fully correct. It is automatically treated as a passed review and cannot be combined with
or
. For content whose result cannot yet be determined, additionally use
, which displays a result such as
. When there is no content that can be assessed, do not provide a score, and do not infer one from the completion status.
Older versions may not support these parameters. First check
cyeam trello card review --help
; if the parameters are unsupported, prompt the user to upgrade. Do not overwrite a CLI that the user has already installed, and do not claim that the score has been synchronized. Scores other than 100 are independent of
: a high grade may still contain errors, and a provisional grade cannot be used to infer that the entire submission has passed.
Retries must use the same UUID, score, provisional flag, body, and result parameters. If the comment was published but updating the description failed, only complete the update and do not publish the comment again. After success, rerunning the same UUID does not replay the previous grading result; use a new UUID for a new grading round so that the history is preserved. Do not edit the same card description concurrently while a result is being published.
Publishing Homework Reviews (Protocol v1)
By default, review feedback should contain only the question number, verdict, score, error category, and redo guidance. Correct answers, complete solutions, and numeric differences that could reveal the answers are for internal verification only and must not be included in
,
, or image/audio attachments. Provide reference answers only when the user explicitly requests them or explicitly permits them in a specified scenario, and only within that scope. A request to check, grade, or correct homework does not imply permission to display answers. Refer to
in the homework skill for the complete rules.
text
cyeam trello card review <card-id> --text <纯文本> [--review-id <UUID>] [--grade 100|优|良|中|差] [--provisional]
cyeam trello card review <card-id> --text-file <UTF-8文件> [--review-id <UUID>]
cyeam trello card review <card-id> --reading-report <asr-review生成的JSON> [--review-id <UUID>]
cyeam trello card review <card-id> --image <本地图片> [--review-id <UUID>]
cyeam trello card review <card-id> --audio <本地音频> [--review-id <UUID>]
Exactly one content parameter must be selected.
is used for English reading: it extracts the
from the
report and calls the server's
/api/homework/reading/regrade
endpoint to regenerate the fixed feedback text and grade. Do not pass
or
at the same time, and
is no longer supported. Rewritten feedback and score fields in the intermediate JSON do not affect the write-back result. Always write to the original card and do not create a card. When there is a score, write
only at the top of the description while preserving the original question and other instructions. The optional
explicitly controls whether the submission contains errors:
moves it to “Needs Correction” and clears
;
treats the review as passed and, if the current state is “Corrected”, preserves that state; otherwise, it moves the card to “Completed” and sets
. When omitted, only the review content is published, and neither the list nor the completion status is changed.
is an exception and is automatically processed as
. Look up target-list IDs on the card's board and create a list automatically if it is missing. Each publication creates one JSON comment beginning with
. Images and audio are first uploaded as native file attachments and then published in the comment by attachment ID. Supported image extensions are jpg/jpeg/png/webp/gif; supported audio extensions are m4a/mp3/wav/aac/ogg/opus/amr/3gp. Files must be non-empty and no larger than 50 MiB. The extension must match the actual file format, with M4A/AAC or MP3 preferred for audio.
A UUID is generated by default. During execution,
and
are written to stderr; alternatively, specify the UUID explicitly on the first submission. A successful response contains
,
,
, and
; media responses also contain
. State is stored in
~/.cyeam/trello-reviews/<UUID>.json
with permissions
, including the body, attachment ID, and action ID, but not the Token. Do not delete state files that may still be needed for retries.
After a failure, rerun the command with the
same UUID, same card, and exactly the same content. The CLI first checks existing native attachments with the same name and card comments using pagination, then recovers uploads or publications that already succeeded. A successful local record is returned directly without publishing the comment again. Changing the content or the presence of errors, including omitting
, under the same UUID produces an error. If the comment was published but the state update failed, retry with exactly the same parameters and UUID to update only the state, without publishing the comment again. After the entire workflow succeeds, rerunning it does not replay the state. Comment recovery excludes identical-text comments that existed before the publication, so a new UUID can publish the same feedback as a new round of history.
If the result of a request is unknown and the query still finds no matching record, the CLI stops by default and does not blindly repeat the POST request. Retry later with the same UUID to verify the result. Only after manually confirming that the previous write failed may you add
to allow another POST request, which still carries a duplication risk. This option requires the original
to be specified explicitly. If a crashed process leaves a
file, first confirm that no process for that submission is still running and then remove the corresponding lock file; preserve the JSON state file.
Use a new UUID for each new grading round so that the history is preserved, and do not delete attachments referenced by old comments. The command does not provide a device Token, upload external links, or modify the original comment. Refer to the repository's
for the complete usage instructions and acceptance boundaries.
Homework uses four unified list statuses: Pending → Completed → Needs Correction → Corrected. “Corrected” means that the child submitted a correction; it does not mean that the re-review has passed. If the corrected submission still contains errors, return it to “Needs Correction”; if it passes, keep it in “Corrected”. The
report adds a
field with the values todo/completed/needs_correction/corrected; a list outside these four is reported as unknown.
preserves the original name, and the correct answer rate must not be inferred from
. Before publishing, base the decision on the latest submission. If there is content whose result cannot yet be determined and it is not possible to confirm that the entire submission has passed, omit
.