@yuiseki/gyazocli 0.8.0 → 0.10.0

package/README.md

@@ -196,6 +196,27 @@ already configured against that server can point at this one instead. Its
 `gyazo_upload` is deliberately absent: nothing here can write to your Gyazo
 account until there is a reason for it to.
 
+## Triage
+
+Going through captures one at a time, deciding something about each:
+
+```bash
+gyazo triage -q "password"
+gyazo triage --id <image_id>          # revisit one
+```
+
+It prints everything a capture carries as markdown, one heading per field, and
+at a terminal asks `Is it safe? [Y/n]` after each. Answers are appended to
+`${XDG_STATE_HOME:-~/.local/state}/gyazocli/triage.jsonl`, outside the cache,
+and a capture already answered is skipped next time.
+
+Answering `n` sets that capture to `only_me`. The public API takes
+`access_policy` at upload and has no endpoint that changes it afterwards, so
+this needs gyazo.com cookies, from `GYAZO_COOKIE_FILE` or
+`~/.config/gyazo/cookie.json` (a browser export works as-is). Without them it
+prints the capture's page URL instead and says nothing was changed, and
+`--no-apply` turns the change off entirely.
+
 ## Agent skill
 
 `skills/gyazo/` is a skill for coding agents that drive the CLI: what the

package/dist/api.js

@@ -12,6 +12,7 @@ exports.listCollections = listCollections;
 exports.getCollectionDetail = getCollectionDetail;
 exports.listCollectionImages = listCollectionImages;
 exports.fetchImageRendition = fetchImageRendition;
+exports.setAccessPolicy = setAccessPolicy;
 exports.uploadImage = uploadImage;
 const axios_1 = __importDefault(require("axios"));
 const form_data_1 = __importDefault(require("form-data"));
@@ -50,6 +51,15 @@ async function requestWithRetry(url, params = {}, headers) {
         return response.data;
     }
     catch (error) {
+        if (error.response && error.response.status === 401) {
+            // The status alone reads as a bug in the caller. It is not: the token
+            // is present and Gyazo will not take it. That happens when it is
+            // mistyped, when it has been revoked, and when Gyazo revokes tokens in
+            // bulk, as it did after the 2026-09-11 incident.
+            throw new Error('Gyazo rejected the access token (401). Issue a new one at ' +
+                'https://gyazo.com/oauth/applications and save it with ' +
+                '`gyazo config set token <token>`.');
+        }
         if (error.response && error.response.status === 429) {
             const retryAfter = parseInt(error.response.headers['retry-after'] || '5', 10);
             console.warn(`Rate limited. Retrying after ${retryAfter} seconds...`);
@@ -136,6 +146,37 @@ async function fetchImageRendition(imageId, width, format = 'webp') {
         format,
     };
 }
+/**
+ * The web app's own endpoint for an existing capture.
+ *
+ * The public API takes `access_policy` when uploading and offers nothing that
+ * changes it afterwards, so this speaks to the same route the site does. It
+ * needs the session cookie and the CSRF token that goes with it: without the
+ * token the request comes back 422 with an empty body.
+ */
+async function setAccessPolicy(imageId, accessPolicy, cookieHeader) {
+    const page = await axios_1.default.get(`${webOrigin()}/${imageId}`, {
+        headers: { Cookie: cookieHeader },
+        responseType: 'text',
+        // A redirect to the login page means the cookies are stale; let it be
+        // seen rather than followed into an HTML page with no token.
+        maxRedirects: 0,
+        validateStatus: (status) => status >= 200 && status < 400,
+    });
+    const token = String(page.data).match(/<meta name="csrf-token" content="([^"]+)"/)?.[1];
+    if (!token) {
+        throw new Error('could not read a CSRF token from gyazo.com; the cookies are probably expired');
+    }
+    const response = await axios_1.default.patch(`${webOrigin()}/api/internal/images/${imageId}`, { access_policy: accessPolicy }, {
+        headers: {
+            Cookie: cookieHeader,
+            'Content-Type': 'application/json',
+            'X-CSRF-Token': token,
+            'X-Requested-With': 'XMLHttpRequest',
+        },
+    });
+    return response.data;
+}
 async function uploadImage(options) {
     const form = new form_data_1.default();
     form.append('access_token', config_1.config.GYAZO_ACCESS_TOKEN || '');

package/dist/commands/config.js

@@ -2,13 +2,31 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerConfigCommand = registerConfigCommand;
 const api_1 = require("../api");
+const config_1 = require("../config");
 const credentials_1 = require("../credentials");
 function registerConfigCommand(program) {
     const configCmd = program.command('config').description('Manage configuration');
     configCmd
         .command('set <key> <value>')
         .description('Set a configuration value')
-        .action((key, value) => {
+        .option('--no-verify', 'save a token without checking it against the API first')
+        .action(async (key, value, options) => {
+        // A token that Gyazo will not accept is worth catching here rather than
+        // at the next command: the page it comes from shows several strings of
+        // the same shape, and a saved bad token replaces a good one.
+        if (key === 'token' && options.verify !== false) {
+            (0, config_1.setAccessToken)(value);
+            try {
+                await (0, api_1.getCurrentUser)();
+            }
+            catch (error) {
+                console.error(`Error: this token was not accepted. ${error.message}`);
+                console.error('Nothing was saved. Check that the value is the access token');
+                console.error('from https://gyazo.com/oauth/applications, not the client ID or secret.');
+                console.error('Save it anyway with --no-verify.');
+                process.exit(1);
+            }
+        }
         (0, credentials_1.setStoredConfig)(key, value);
     });
     configCmd

package/dist/commands/sync.js

@@ -14,6 +14,8 @@ function registerSyncCommand(program) {
         .option('--date <yyyy|yyyy-mm|yyyy-mm-dd>', 'sync only this date/month/year range')
         .option('--max-pages <number>', 'max pages to fetch', '10')
         .option('--query <query>', 'fill the cache from a search instead of the listing')
+        .option('--refresh', 'fetch every capture again, even one already cached')
+        .option('--continue', 'resume the last walk of this query instead of starting at the top')
         .action(async (options) => {
         await (0, credentials_1.ensureAccessToken)();
         if (options.date && options.days) {
@@ -31,7 +33,32 @@ function registerSyncCommand(program) {
             console.error('  --query "has:exif since:2026-08-01 until:2026-08-31"');
             process.exit(1);
         }
+        if (options.continue && !options.query) {
+            console.error('Error: --continue needs --query, because it resumes a query.');
+            process.exit(1);
+        }
         const maxPages = (0, options_1.parsePositiveIntegerOption)(options.maxPages, '--max-pages');
+        /** The day part of an instant, in local time, as the operators want it. */
+        const dayOf = (date) => {
+            const pad = (value) => String(value).padStart(2, '0');
+            return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+        };
+        let query = options.query;
+        if (options.continue) {
+            if (/\b(date|since|until):/i.test(query)) {
+                console.error('Error: --continue cannot resume a query that bounds its own dates.');
+                console.error('Hint: drop date:, since: and until: from --query, or drop --continue.');
+                process.exit(1);
+            }
+            const state = (0, storage_1.loadSyncState)(query);
+            if (state) {
+                query = `${query} until:${state.oldestDay}`;
+                console.log(`Resuming from ${state.oldestDay} (walked ${state.updatedAt}).`);
+            }
+            else {
+                console.log('Nothing walked for this query yet; starting at the top.');
+            }
+        }
         let startDate;
         let endDate;
         if (options.date) {
@@ -49,16 +76,17 @@ function registerSyncCommand(program) {
             startDate.setDate(startDate.getDate() - days - 1);
             startDate.setHours(0, 0, 0, 0);
         }
-        if (options.query) {
-            console.log(`Syncing images matching ${JSON.stringify(options.query)}...`);
+        if (query) {
+            console.log(`Syncing images matching ${JSON.stringify(query)}...`);
         }
         else {
             console.log(`Syncing images between ${startDate.toISOString()} and ${endDate.toISOString()}...`);
         }
         const hourlyIndices = new Map();
+        let oldestSeen = null;
         for (let page = 1; page <= maxPages; page++) {
-            const images = options.query
-                ? await (0, api_1.searchImages)(options.query, page, 100)
+            const images = query
+                ? await (0, api_1.searchImages)(query, page, 100)
                 : await (0, api_1.listImages)(page, 100);
             if (images.length === 0)
                 break;
@@ -67,14 +95,17 @@ function registerSyncCommand(program) {
                 const createdAt = new Date(img.created_at);
                 // A query says for itself what it covers, and the results are not
                 // ordered predictably enough to stop early on a date.
-                if (!options.query && createdAt > endDate) {
+                if (!query && createdAt > endDate) {
                     // Skip images newer than target range.
                     continue;
                 }
-                if (!options.query && createdAt < startDate) {
+                if (!query && createdAt < startDate) {
                     reachedLimit = true;
                     break;
                 }
+                if (!oldestSeen || createdAt < oldestSeen) {
+                    oldestSeen = createdAt;
+                }
                 // Add to hourly index
                 const y = createdAt.getFullYear().toString();
                 const m = (createdAt.getMonth() + 1).toString().padStart(2, '0');
@@ -84,8 +115,13 @@ function registerSyncCommand(program) {
                 if (!hourlyIndices.has(key))
                     hourlyIndices.set(key, new Set());
                 hourlyIndices.get(key)?.add(img.image_id);
-                const cached = (0, storage_1.loadImageCache)(img.image_id);
-                if (cached && cached.ocr) {
+                // Already fetched is already fetched. This used to test `cached.ocr`,
+                // which is null in every response the API returns -- the OCR text
+                // lives under `metadata` -- so the check never fired and every sync
+                // re-fetched everything it had. On an API with undocumented rate
+                // limits that is the expensive kind of mistake.
+                const cached = options.refresh ? null : (0, storage_1.loadImageCache)(img.image_id);
+                if (cached) {
                     process.stdout.write(`s`);
                     continue;
                 }
@@ -102,6 +138,12 @@ function registerSyncCommand(program) {
             console.log(`\nPage ${page} processed.`);
             if (reachedLimit)
                 break;
+            // A breath between pages. The rate limits here are real and
+            // undocumented, and a walk of a hundred pages is exactly the shape
+            // that finds them.
+            if (page < maxPages) {
+                await new Promise((resolve) => setTimeout(resolve, 1000));
+            }
         }
         // Save hourly indices
         console.log(`Updating hourly indices...`);
@@ -111,6 +153,16 @@ function registerSyncCommand(program) {
             const merged = Array.from(new Set([...existing, ...ids]));
             (0, storage_1.saveHourlyCache)(y, m, d, h, merged);
         }
+        // Remember how far back this query got, so a later --continue can pick
+        // up there rather than walking the same pages again. Only for a query
+        // the caller did not bound itself: a bounded one says what it covers.
+        if (options.query && oldestSeen && !/\b(date|since|until):/i.test(options.query)) {
+            (0, storage_1.saveSyncState)({
+                query: options.query,
+                oldestDay: dayOf(oldestSeen),
+                updatedAt: new Date().toISOString(),
+            });
+        }
         console.log(`Sync complete.`);
     });
 }

package/dist/commands/triage.js

@@ -0,0 +1,358 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.highlightTermsOf = highlightTermsOf;
+exports.registerTriageCommand = registerTriageCommand;
+/**
+ * The `triage` command: a search, rendered as markdown for reading rather than
+ * for parsing.
+ *
+ * `ls` and `search` print one line per capture, which is the right shape for
+ * scanning a day. Going through captures one at a time, deciding something
+ * about each, wants the opposite: everything a capture carries, laid out, with
+ * nothing invented and nothing hidden.
+ */
+const node_readline_1 = __importDefault(require("node:readline"));
+const api_1 = require("../api");
+const credentials_1 = require("../credentials");
+const format_1 = require("../format");
+const cookies_1 = require("../cookies");
+const ids_1 = require("../ids");
+const options_1 = require("../options");
+const memory_1 = require("../services/memory");
+const triage_ledger_1 = require("../services/triage-ledger");
+/**
+ * Fields worth a heading, in the order a person reads them. The id, the URLs
+ * and the coordinates are deliberately absent: the id is the heading, and the
+ * rest is noise when the job is deciding something about a capture.
+ */
+const FIELD_ORDER = [
+    // First, because it is what a triage decision often turns on.
+    'access_policy',
+    'created_at',
+    'app',
+    'title',
+    'desc',
+    'page_url',
+    'alt_text',
+    'ocr',
+    'address',
+    'objects',
+];
+const CYAN = '\u001b[36m';
+const RESET = '\u001b[0m';
+const ORANGE = '\u001b[38;5;208m';
+/** Back to the default foreground, rather than resetting every attribute. */
+const PLAIN = '\u001b[39m';
+/** Operators whose value never appears in the text, so painting it is noise. */
+const STRUCTURAL_KEYS = new Set(['has', 'type', 'date', 'since', 'until']);
+/**
+ * The parts of a query that can show up in what a capture says: bare words,
+ * and the values of the operators that match text. `has:exif` contributes
+ * nothing, and a negated term should not be there to find.
+ */
+function highlightTermsOf(query) {
+    const terms = [];
+    // Quoted values hold spaces: app:"Gyazo Android".
+    for (const token of query.match(/(?:[^\s"]|"[^"]*")+/g) || []) {
+        if (token.startsWith('-') || token === 'OR' || token === 'or')
+            continue;
+        const separator = token.indexOf(':');
+        const raw = separator === -1 ? token : token.slice(separator + 1);
+        if (separator !== -1 && STRUCTURAL_KEYS.has(token.slice(0, separator).toLowerCase()))
+            continue;
+        const value = raw.replace(/^"|"$/g, '').trim();
+        if (value)
+            terms.push(value);
+    }
+    return terms;
+}
+function escapeForRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Paint every occurrence of a term, keeping the text's own case. */
+function highlight(value, terms) {
+    if (terms.length === 0)
+        return value;
+    const pattern = new RegExp(terms.map(escapeForRegExp).join('|'), 'gi');
+    return value.replace(pattern, (match) => `${ORANGE}${match}${PLAIN}`);
+}
+function text(value) {
+    if (value === null || value === undefined)
+        return undefined;
+    if (typeof value === 'string')
+        return (0, format_1.normalizeText)(value);
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    return undefined;
+}
+/**
+ * What a capture actually carries, flattened to a name and a block of text.
+ * A field that is absent, null or empty is left out rather than printed as a
+ * heading with nothing under it.
+ */
+function fieldsOf(image) {
+    const metadata = image?.metadata || {};
+    const ocr = metadata.ocr ?? image?.ocr;
+    const exif = metadata.exif_normalized ?? image?.exif_normalized;
+    const address = metadata.exif_address?.ja?.address ?? metadata.exif_address?.en?.address ?? undefined;
+    const objects = Array.isArray(metadata.localized_object_annotations)
+        ? metadata.localized_object_annotations
+        : metadata.localizedObjectAnnotations;
+    const candidates = {
+        // The API leaves this unset on most captures, where it means the default.
+        // Reading a hundred sections looking for the ones that are not `anyone`
+        // is easier when every section says which it is.
+        access_policy: text(image?.access_policy) ?? 'anyone',
+        created_at: image?.created_at ? (0, format_1.formatCreatedAtJa)(image.created_at) : undefined,
+        type: text(image?.type),
+        permalink_url: text(image?.permalink_url),
+        url: text(image?.url),
+        app: text(metadata.app),
+        title: text(metadata.title),
+        desc: text(metadata.desc),
+        page_url: text(metadata.url),
+        alt_text: text(image?.alt_text),
+        ocr: text(ocr?.description),
+        ocr_locale: text(ocr?.locale),
+        latitude: text(exif?.latitude),
+        longitude: text(exif?.longitude),
+        address: text(address),
+        objects: Array.isArray(objects)
+            ? objects
+                .map((o) => {
+                const name = text(o?.name_ja || o?.nameJa || o?.name);
+                const score = typeof o?.score === 'number' ? ` (${(o.score * 100).toFixed(1)}%)` : '';
+                return name ? `${name}${score}` : undefined;
+            })
+                .filter(Boolean)
+                .join('\n') || undefined
+            : undefined,
+    };
+    return FIELD_ORDER.map((key) => [key, candidates[key]]).filter((entry) => Boolean(entry[1]));
+}
+function registerTriageCommand(program) {
+    program
+        .command('triage [query]')
+        .description('Search, and go through the captures one at a time')
+        .option('-q, --query <query>', 'the search query')
+        .option('-l, --limit <number>', 'how many captures to go through in this run', '20')
+        .option('--max-pages <number>', 'how many search pages to walk looking for them', '20')
+        .option('--id <image_id...>', 'go through exactly these captures, answered or not')
+        .option('--color <when>', 'colour the headings: auto, always or never', 'auto')
+        .option('-i, --interactive', 'ask about each capture and record the answer')
+        .option('--no-interactive', 'print without asking, even at a terminal')
+        .option('--again', 'ask again about captures already answered')
+        .option('--cookies <path>', 'gyazo.com cookies, for making a capture private')
+        .option('--no-apply', 'answer without changing anything on Gyazo')
+        .option('--no-cache', 'force fetch from API')
+        .action(async (positional, options) => {
+        await (0, credentials_1.ensureAccessToken)();
+        const ids = options.id || [];
+        const query = (0, format_1.normalizeText)(options.query || positional) || '';
+        if (!query && ids.length === 0) {
+            console.error('Error: Query is required.');
+            console.error('Hint: gyazo triage -q "password"');
+            console.error('      gyazo triage --id <image_id>   to revisit one');
+            process.exit(1);
+        }
+        const limit = (0, options_1.parsePositiveIntegerOption)(options.limit, '--limit');
+        const maxPages = (0, options_1.parsePositiveIntegerOption)(options.maxPages, '--max-pages');
+        // Colour when a person is reading, not when the output is being piped
+        // into a file. `--color always` is for a pager that understands it.
+        const colour = options.color === 'always' ||
+            (options.color !== 'never' && Boolean(process.stdout.isTTY) && !process.env.NO_COLOR);
+        // Asking only makes sense with someone there to answer. A pipe on either
+        // side means this is feeding a file, not a person.
+        const interactive = options.interactive === true ||
+            (options.interactive !== false &&
+                Boolean(process.stdin.isTTY) &&
+                Boolean(process.stdout.isTTY));
+        const terms = colour ? highlightTermsOf(query) : [];
+        // Read once, so a long triage does not touch the file per answer.
+        const cookieHeader = options.apply === false ? undefined : (0, cookies_1.loadCookieHeader)(options.cookies);
+        const print = (image, index) => {
+            console.log('');
+            if (index > 0) {
+                console.log('---');
+                console.log('');
+            }
+            const heading = `# ${image.image_id}`;
+            console.log(colour ? `${CYAN}${heading}${RESET}` : heading);
+            for (const [key, value] of fieldsOf(image)) {
+                console.log('');
+                console.log(`## ${key}`);
+                console.log('');
+                console.log(highlight(value, terms));
+            }
+        };
+        const goThrough = async (captures, skipped, pagesWalked) => {
+            if (!interactive) {
+                captures.forEach(print);
+                return;
+            }
+            // Lines are pulled from an iterator rather than asked for with
+            // rl.question: with piped input, question() resolves once and then
+            // never again, so everything after the first answer is lost.
+            const lines = node_readline_1.default.createInterface({ input: process.stdin });
+            const answers = lines[Symbol.asyncIterator]();
+            const ask = async (prompt) => {
+                process.stdout.write(prompt);
+                const { value, done } = await answers.next();
+                return done ? null : String(value);
+            };
+            const counts = { safe: 0, unsafe: 0 };
+            const toMakePrivate = [];
+            let madePrivate = 0;
+            let warnedAboutCookies = false;
+            let asked = 0;
+            try {
+                for (const [index, image] of captures.entries()) {
+                    print(image, index);
+                    console.log('');
+                    const raw = await ask('Is it safe? [Y/n] ');
+                    // Enter takes the default. q stops, and so does end of input: no
+                    // answer is not the same as "safe".
+                    if (raw === null) {
+                        console.log('');
+                        break;
+                    }
+                    const answer = raw.trim().toLowerCase();
+                    if (answer === 'q' || answer === 'quit')
+                        break;
+                    const verdict = answer === 'n' || answer === 'no' ? 'unsafe' : 'safe';
+                    (0, triage_ledger_1.appendTriageEntry)({
+                        image_id: image.image_id,
+                        verdict,
+                        at: new Date().toISOString(),
+                        query: query || undefined,
+                    });
+                    counts[verdict]++;
+                    asked++;
+                    if (verdict === 'unsafe') {
+                        const link = image.permalink_url || `https://gyazo.com/${image.image_id}`;
+                        const paint = (line) => (colour ? `${ORANGE}${line}${PLAIN}` : line);
+                        if (options.apply === false) {
+                            toMakePrivate.push(link);
+                            console.log(paint(`→ ${link}`));
+                        }
+                        else if (!cookieHeader) {
+                            // The public API has no way to change this, so without
+                            // cookies the honest move is to hand over the link and say
+                            // why, once.
+                            toMakePrivate.push(link);
+                            console.log(paint(`→ ${link}`));
+                            if (!warnedAboutCookies) {
+                                console.log('  (no gyazo.com cookies found, so nothing was changed. Put them in ' +
+                                    '~/.config/gyazo/cookie.json to have this set only_me for you.)');
+                                warnedAboutCookies = true;
+                            }
+                        }
+                        else {
+                            try {
+                                await (0, api_1.setAccessPolicy)(image.image_id, 'only_me', cookieHeader);
+                                console.log(paint(`→ only_me: ${link}`));
+                                madePrivate++;
+                            }
+                            catch (error) {
+                                // A failure here is the interesting kind: the answer is
+                                // recorded, the capture is still public, and saying so is
+                                // the only way the difference is visible.
+                                toMakePrivate.push(link);
+                                console.log(paint(`→ ${link}`));
+                                console.log(`  could not set only_me: ${error.message}`);
+                            }
+                        }
+                    }
+                }
+            }
+            finally {
+                lines.close();
+            }
+            console.log('');
+            console.log(`${asked} answered: ${counts.safe} safe, ${counts.unsafe} unsafe` +
+                (madePrivate > 0 ? `, ${madePrivate} set only_me` : '') +
+                '.');
+            if (skipped > 0) {
+                console.log(`${skipped} skipped as already answered, ${pagesWalked} pages walked.`);
+            }
+            if (toMakePrivate.length > 0) {
+                console.log('');
+                console.log(`${toMakePrivate.length} to make private (only_me), on their own pages:`);
+                for (const link of toMakePrivate)
+                    console.log(`  ${link}`);
+            }
+            console.log(`Written to ${(0, triage_ledger_1.getTriageLedgerPath)()}`);
+        };
+        try {
+            console.log(`triage: ${query || ids.join(', ')}`);
+            // Named captures are fetched as named, and asked about whether or not
+            // they were answered before: naming one is how a mistake is corrected.
+            if (ids.length > 0) {
+                const named = [];
+                for (const given of ids) {
+                    const imageId = (0, ids_1.normalizeImageId)(given);
+                    if (!imageId) {
+                        console.error(`Error: '${given}' is not a Gyazo image ID or URL.`);
+                        process.exit(1);
+                    }
+                    named.push(await (0, api_1.getImageDetail)(imageId));
+                }
+                await goThrough(named, 0, 0);
+                return;
+            }
+            // Walk the search until `limit` captures that have not been answered
+            // are in hand. A page where everything is already answered is not the
+            // end of the road, which is what stopping at one page made it.
+            const answered = options.again ? new Map() : (0, triage_ledger_1.loadTriageVerdicts)();
+            const selected = [];
+            let pagesWalked = 0;
+            let skipped = 0;
+            for (let page = 1; page <= maxPages && selected.length < limit; page++) {
+                const found = await (0, api_1.searchImages)(query, page, 100);
+                pagesWalked = page;
+                if (!found || found.length === 0)
+                    break;
+                for (const image of found) {
+                    if (answered.has(image.image_id)) {
+                        skipped++;
+                        continue;
+                    }
+                    selected.push(image);
+                    if (selected.length >= limit)
+                        break;
+                }
+                if (found.length < 100)
+                    break;
+            }
+            if (selected.length === 0) {
+                console.log('');
+                if (skipped > 0) {
+                    console.log(`Nothing left to ask about: ${skipped} already answered, ` +
+                        `${pagesWalked} pages walked.`);
+                    console.log(`Answers so far: ${(0, triage_ledger_1.getTriageLedgerPath)()}`);
+                }
+                else {
+                    console.log('No captures matched.');
+                }
+                return;
+            }
+            // The search endpoint returns a lean image: no OCR, no coordinates.
+            // Triage is about what a capture says, so fetch the rest.
+            const enriched = await (0, memory_1.enrichImageLocations)(selected, {
+                useCache: options.cache !== false,
+                limit: selected.length,
+            });
+            console.log(`${enriched.images.length} captures` +
+                (skipped > 0 ? `, ${skipped} already answered and skipped` : '') +
+                `, ${pagesWalked} pages walked.`);
+            await goThrough(enriched.images, skipped, pagesWalked);
+        }
+        catch (error) {
+            console.error('Error triaging images:', error.message);
+            process.exit(1);
+        }
+    });
+}

package/dist/cookies.js

@@ -0,0 +1,89 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findCookieFile = findCookieFile;
+exports.buildCookieHeader = buildCookieHeader;
+exports.loadCookieHeader = loadCookieHeader;
+/**
+ * Browser cookies for gyazo.com, for the one thing the API cannot do.
+ *
+ * `access_policy` is an upload parameter and there is no endpoint that updates
+ * it afterwards, so making an existing capture private means asking the web
+ * app the way the web app asks itself: a session cookie and a CSRF token.
+ *
+ * The file holds a live session. It is read when needed, never logged, and
+ * never written to.
+ */
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const GYAZO_DOMAIN = /(^|\.)gyazo\.com$/i;
+/**
+ * Where to look, nearest intention first. A file named outright is the only
+ * candidate: falling back from a path someone gave would use credentials they
+ * did not point at, which is the last thing this should do.
+ */
+function candidatePaths() {
+    if (process.env.GYAZO_COOKIE_FILE)
+        return [process.env.GYAZO_COOKIE_FILE];
+    const paths = [];
+    const home = os_1.default.homedir();
+    paths.push(path_1.default.join(home, '.config', 'gyazo', 'cookie.json'));
+    paths.push(path_1.default.join(home, '.config', 'gyazo', 'cookies.json'));
+    // Handy while working in a checkout, though it only applies from there.
+    paths.push(path_1.default.join(process.cwd(), '.cookies', 'gyazo.com.json'));
+    return paths;
+}
+function findCookieFile(explicit) {
+    const paths = explicit ? [explicit] : candidatePaths();
+    return paths.find((candidate) => fs_1.default.existsSync(candidate));
+}
+/**
+ * A `Cookie` header from whatever shape the file is in: a browser export
+ * (an array of `{name, value, domain}`), a plain `{name: value}` object, or a
+ * header string already. Entries belonging to another domain are left out.
+ */
+function buildCookieHeader(contents) {
+    const trimmed = contents.trim();
+    if (trimmed === '')
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        // Already a header, or a cookie file this does not understand.
+        return trimmed.includes('=') ? trimmed : undefined;
+    }
+    const pairs = [];
+    if (Array.isArray(parsed)) {
+        for (const entry of parsed) {
+            if (!entry || typeof entry.name !== 'string')
+                continue;
+            if (typeof entry.domain === 'string' && !GYAZO_DOMAIN.test(entry.domain.replace(/^\./, ''))) {
+                continue;
+            }
+            pairs.push(`${entry.name}=${entry.value ?? ''}`);
+        }
+    }
+    else if (parsed && typeof parsed === 'object') {
+        for (const [name, value] of Object.entries(parsed)) {
+            if (typeof value === 'string')
+                pairs.push(`${name}=${value}`);
+        }
+    }
+    return pairs.length > 0 ? pairs.join('; ') : undefined;
+}
+function loadCookieHeader(explicit) {
+    const file = findCookieFile(explicit);
+    if (!file)
+        return undefined;
+    try {
+        return buildCookieHeader(fs_1.default.readFileSync(file, 'utf-8'));
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/format.js

@@ -20,6 +20,7 @@ exports.buildEnLocationLabel = buildEnLocationLabel;
 exports.extractImageAddressText = extractImageAddressText;
 exports.extractImageLocationLabel = extractImageLocationLabel;
 exports.truncateText = truncateText;
+exports.formatCreatedAtJa = formatCreatedAtJa;
 exports.formatCreatedAt = formatCreatedAt;
 exports.shortenImageId = shortenImageId;
 exports.formatTerminalLink = formatTerminalLink;
@@ -229,12 +230,37 @@ function truncateText(value, maxLength) {
         return value.slice(0, maxLength);
     return `${value.slice(0, maxLength - 3)}...`;
 }
+const JA_WEEKDAYS = ['日', '月', '火', '水', '木', '金', '土'];
+/**
+ * A timestamp as the person who took the capture experienced it: their own
+ * clock, in Japanese. The API sends UTC, so this converts rather than reading
+ * the digits out of the string.
+ */
+function formatCreatedAtJa(value) {
+    const at = new Date(value);
+    if (Number.isNaN(at.getTime()))
+        return value;
+    const pad = (n) => String(n).padStart(2, '0');
+    return (`${at.getFullYear()}年${at.getMonth() + 1}月${at.getDate()}日` +
+        `(${JA_WEEKDAYS[at.getDay()]}) ${pad(at.getHours())}:${pad(at.getMinutes())}`);
+}
+/**
+ * A timestamp on the reader's own clock.
+ *
+ * This used to lift the digits out of the string, which showed the API's UTC
+ * as if it were local time: a capture taken at 18:09 in Tokyo was listed as
+ * 09:09. The filters were always local, so only the display was wrong, and it
+ * was wrong by a whole timezone.
+ */
 function formatCreatedAt(value) {
-    const match = value.match(/^(\d{4}-\d{2}-\d{2})[T ](\d{2}):(\d{2})/);
-    if (match) {
-        return `${match[1]} ${match[2]}:${match[3]}`;
+    const at = new Date(value);
+    if (Number.isNaN(at.getTime())) {
+        const match = value.match(/^(\d{4}-\d{2}-\d{2})[T ](\d{2}):(\d{2})/);
+        return match ? `${match[1]} ${match[2]}:${match[3]}` : value;
     }
-    return value;
+    const pad = (n) => String(n).padStart(2, '0');
+    return (`${at.getFullYear()}-${pad(at.getMonth() + 1)}-${pad(at.getDate())} ` +
+        `${pad(at.getHours())}:${pad(at.getMinutes())}`);
 }
 function shortenImageId(imageId) {
     if (!imageId)

package/dist/index.js

@@ -12,6 +12,7 @@ const list_1 = require("./commands/list");
 const get_1 = require("./commands/get");
 const collection_1 = require("./commands/collection");
 const search_1 = require("./commands/search");
+const triage_1 = require("./commands/triage");
 const apps_1 = require("./commands/apps");
 const domains_1 = require("./commands/domains");
 const tags_1 = require("./commands/tags");
@@ -26,12 +27,13 @@ program
     .name('gyazo')
     .description('Gyazo Memory CLI for AI Secretary')
     .option('--mcp-server', 'run as a Model Context Protocol server over stdio')
-    .version('0.8.0');
+    .version('0.10.0');
 (0, config_1.registerConfigCommand)(program);
 (0, list_1.registerListCommand)(program);
 (0, get_1.registerGetCommand)(program);
 (0, collection_1.registerCollectionCommand)(program);
 (0, search_1.registerSearchCommand)(program);
+(0, triage_1.registerTriageCommand)(program);
 (0, apps_1.registerAppsCommand)(program);
 (0, domains_1.registerDomainsCommand)(program);
 (0, tags_1.registerTagsCommand)(program);

package/dist/services/triage-ledger.js

@@ -0,0 +1,59 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTriageLedgerPath = getTriageLedgerPath;
+exports.loadTriageEntries = loadTriageEntries;
+exports.loadTriageVerdicts = loadTriageVerdicts;
+exports.appendTriageEntry = appendTriageEntry;
+/**
+ * What was decided about a capture, and where that is kept.
+ *
+ * Deliberately not under the cache: the cache holds copies of things Gyazo can
+ * send again, and can be deleted to reclaim disk. A judgement cannot be
+ * fetched again, so it lives in the state directory and survives `rm -rf
+ * ~/.cache/gyazocli`.
+ */
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+function getTriageLedgerPath() {
+    const base = process.env.GYAZO_STATE_DIR ||
+        process.env.XDG_STATE_HOME ||
+        path_1.default.join(os_1.default.homedir(), '.local', 'state');
+    const dir = path_1.default.join(base, 'gyazocli');
+    if (!fs_1.default.existsSync(dir)) {
+        fs_1.default.mkdirSync(dir, { recursive: true });
+    }
+    return path_1.default.join(dir, 'triage.jsonl');
+}
+function loadTriageEntries() {
+    const file = getTriageLedgerPath();
+    if (!fs_1.default.existsSync(file))
+        return [];
+    return fs_1.default
+        .readFileSync(file, 'utf-8')
+        .split('\n')
+        .filter((line) => line.trim() !== '')
+        .map((line) => {
+        try {
+            return JSON.parse(line);
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((entry) => entry !== null);
+}
+/** The latest verdict for each capture, since the file is append-only. */
+function loadTriageVerdicts() {
+    const byImage = new Map();
+    for (const entry of loadTriageEntries()) {
+        byImage.set(entry.image_id, entry);
+    }
+    return byImage;
+}
+function appendTriageEntry(entry) {
+    fs_1.default.appendFileSync(getTriageLedgerPath(), `${JSON.stringify(entry)}\n`, 'utf-8');
+}

package/dist/storage.js

@@ -15,8 +15,11 @@ exports.saveHourlyCache = saveHourlyCache;
 exports.loadHourlyCache = loadHourlyCache;
 exports.saveHourlyMetadataCache = saveHourlyMetadataCache;
 exports.loadHourlyMetadataCache = loadHourlyMetadataCache;
+exports.loadSyncState = loadSyncState;
+exports.saveSyncState = saveSyncState;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
 const os_1 = __importDefault(require("os"));
 function getCacheDir() {
     if (process.env.GYAZO_CACHE_DIR) {
@@ -105,3 +108,25 @@ function loadHourlyMetadataCache(kind, year, month, day, hour) {
     }
     return null;
 }
+function getSyncStatePath(query) {
+    const dir = path_1.default.join(getCacheDir(), 'sync');
+    if (!fs_1.default.existsSync(dir)) {
+        fs_1.default.mkdirSync(dir, { recursive: true });
+    }
+    const key = crypto_1.default.createHash('sha1').update(query).digest('hex');
+    return path_1.default.join(dir, `${key}.json`);
+}
+function loadSyncState(query) {
+    const file = getSyncStatePath(query);
+    if (!fs_1.default.existsSync(file))
+        return null;
+    try {
+        return JSON.parse(fs_1.default.readFileSync(file, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function saveSyncState(state) {
+    fs_1.default.writeFileSync(getSyncStatePath(state.query), JSON.stringify(state, null, 2));
+}

package/docs/ADR/003-cli-structure.md

@@ -13,12 +13,16 @@ Adopt and document the existing top-level command structure.
 
 ### 1. Program Metadata
 - Binary name: `gyazo`
-- Version: `0.8.0`
+- Version: `0.10.0`
 - Description: `Gyazo Memory CLI for AI Secretary`
 
 ### 2. Commands
 - `gyazo config set <key> <value>`
   - Currently supported key: `token`
+  - Options:
+    - `--no-verify` (save a token without checking it against the API first)
+  - A token is checked against `/api/users/me` before it is saved, and nothing
+    is written when Gyazo rejects it
 - `gyazo config get <key>`
   - `token` is masked
   - `me` fetches `/api/users/me`
@@ -48,6 +52,50 @@ Adopt and document the existing top-level command structure.
     - `-l, --limit <number>` (default: `20`)
     - `-j, --json`
     - `--no-cache`
+- `gyazo triage [query]`
+  - Markdown for reading a search result capture by capture: the image ID as
+    `#`, one `##` heading per field it carries, captures separated by `---`
+  - Options:
+    - `-q, --query <query>` (the query, also accepted as a bare argument)
+    - `-l, --limit <number>` (default: `20`; how many captures this run goes
+      through, not an API page size)
+    - `--max-pages <number>` (default: `20`; pages of 100 to walk looking for
+      captures not yet answered)
+    - `--color <auto|always|never>` (default: `auto`, meaning a terminal)
+    - `-i, --interactive` / `--no-interactive` (default: interactive when both
+      stdin and stdout are a terminal)
+    - `--again` (ask again about captures already answered)
+    - `--no-cache`
+  - What the query matched is painted orange, case kept. Bare words and the
+    values of text operators count; `has:`, `type:`, `date:`, `since:` and
+    `until:` values, negated terms and `OR` do not. Only when colour is on,
+    so piped output stays plain
+  - `access_policy` is printed first, and an unset one is printed as `anyone`:
+    the API leaves it unset on most captures, and a reader looking for
+    `only_me` is better served by every section saying which it is
+  - Captures already answered are skipped, and the walk continues to the next
+    page rather than stopping: a page where everything has been answered is not
+    the end of the results
+  - `--id <image_id...>` goes through exactly those captures, answered or not,
+    which is how a mistaken answer is corrected. The ledger is append-only and
+    the last answer for a capture wins
+  - Answering `n` sets the capture to `only_me` when gyazo.com cookies are
+    available, and otherwise prints its page URL and says why. Gyazo's public
+    API takes `access_policy` at upload and has no endpoint that changes it
+    afterwards, so this speaks to the web app's own route the way the site
+    does: a session cookie plus the CSRF token from the capture's page. Without
+    the token the request answers 422 with an empty body
+  - Cookies are looked for at `GYAZO_COOKIE_FILE`, then
+    `~/.config/gyazo/cookie.json`, then `~/.config/gyazo/cookies.json`, then
+    `./.cookies/gyazo.com.json`. A path given outright is the only candidate.
+    A browser export, a `{name: value}` object and a header string are all
+    accepted, and entries for other domains are dropped
+  - `--no-apply` answers without changing anything
+  - Interactive mode asks `Is it safe? [Y/n]` per capture. Enter takes the
+    default, `n` marks it unsafe, `q` or end of input stops and keeps what was
+    answered. Answers are appended to
+    `${XDG_STATE_HOME:-~/.local/state}/gyazocli/triage.jsonl`, outside the
+    cache, because a judgement cannot be fetched again
 - `gyazo apps`
   - Default range: from 8 days ago to yesterday
   - Options:
@@ -120,10 +168,16 @@ Adopt and document the existing top-level command structure.
     - `--max-pages <number>` (default: `10`)
     - `--query <query>` (fill from a search instead of the listing; not with
       `--date` or `--days`, because the range belongs inside the query)
+    - `--refresh` (fetch every capture again, even one already cached)
+    - `--continue` (resume the last walk of this query, with `--query`)
 - `gyazo import <type> <dir>`
   - Supported types: `json`, `hourly`
 
 ### 3. Output and Behavior Notes
+- Timestamps are printed on the reader's own clock. The API sends UTC, and
+  until 2026-09-16 the display lifted the digits out of the string, so a
+  capture taken at 18:09 in Tokyo was listed as 09:09. The `--date`, `--hour`
+  and `--today` filters were always local; only the display was wrong.
 - `-j, --json` is available on `config get`, `list`, `get`, `search`, `apps`, `domains`, `tags`, `locations`, and `summary`.
 - `summary` default output is Markdown with headings (`## Gyazo Summary`, `### YYYY-MM-DD`) and nested bullet lists.
 - There are no global `--plain` or `--verbose` flags in current implementation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yuiseki/gyazocli",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Gyazo Memory CLI for AI Secretary",
   "repository": {
     "type": "git",

package/skills/gyazo/SKILL.md

@@ -13,6 +13,12 @@ questions about the same period are answered locally.
 Check `gyazo config get me` first when a token might be missing; it prints the
 account or exits non-zero. Set one with `gyazo config set token <token>`.
 
+A 401 means Gyazo will not take the token that is there, which is a different
+problem from not having one: it has been mistyped or revoked. Say so and stop,
+rather than retrying or reaching for another command; every authenticated path
+will answer the same way. `config set token` checks a token against the API
+before saving it, so a bad one cannot quietly replace a working one.
+
 Every command exits non-zero on failure, so `&&` chains and `set -e` behave.
 
 ## Reading captures
@@ -25,6 +31,7 @@ gyazo ls --hour 2026-08-30-14        # one hour, from the cache only
 gyazo ls --photos                    # shorthand for has:location
 gyazo get <image_id>                 # one capture in detail
 gyazo get <image_id> --ocr           # just the OCR text
+gyazo get <image_id> --objects       # just what was detected in it
 gyazo <image_id>                     # same as get
 gyazo <https://gyazo.com/...>        # same as get
 gyazo ./screenshot.png               # an existing file uploads instead
@@ -61,6 +68,28 @@ Three things worth knowing before composing a query:
 - **There is no coordinate or radius search.** Search by place with `address:`,
   which matches the address in any language and matches postal codes too.
 
+## Going through captures one at a time
+
+```bash
+gyazo triage -q "password"                 # markdown, one section per capture
+gyazo triage -q "API key" --limit 50
+gyazo triage --id <image_id>               # revisit one, answered or not
+gyazo triage -q "password" --no-interactive > review.md
+```
+
+`triage` prints everything a capture carries, one `##` heading per field it
+has, with the image ID as `#` and `---` between captures. At a terminal it
+asks `Is it safe? [Y/n]` after each one and records the answer in
+`${XDG_STATE_HOME:-~/.local/state}/gyazocli/triage.jsonl`; a capture already
+answered is skipped next time, and the walk pages on to find ones that are not.
+
+Answering `n` sets that capture to `only_me` when gyazo.com cookies are
+available, because the public API cannot change an access policy after upload.
+
+For an agent: pipe it (`--no-interactive`) and read the output. Do not answer
+the prompts on the user's behalf. Whether a capture is safe to leave public is
+theirs to decide, and `n` writes to their account.
+
 ## Summaries and rankings
 
 ```bash
@@ -98,6 +127,7 @@ endpoint returns the first 100 and cannot page.
 gyazo sync --days 7                  # yesterday back through 7 days
 gyazo sync --date 2026-08            # a whole month
 gyazo sync --query "has:exif OR has:location" --max-pages 20
+gyazo sync --query "has:exif" --max-pages 20 --continue   # carry on from last time
 ```
 
 `sync` covers yesterday backwards and never today, because today is still
@@ -108,8 +138,16 @@ command with `--today`.
 gather one kind of capture without walking past everything else: photographs
 are a small fraction of a day's screenshots. Put any date range inside the
 query (`date:2026-08`, `since:... until:...`) rather than in `--date`, which
-`--query` refuses. Budget about 40 seconds per page of 100 captures that are
-not cached yet.
+`--query` refuses.
+
+A capture already in the cache is not fetched again, so a repeated sync costs
+only the search pages: 100 cached captures take under a second, 100 new ones
+about 40 seconds. `--continue` remembers how far back the last walk of that
+query reached and resumes with `until:<that day>`, which is how to backfill a
+long history a few hundred pages at a time without asking for the same pages
+twice. Gyazo rate-limits without documenting it, so prefer resuming over
+re-walking, and leave `--refresh` alone unless a capture really needs
+re-fetching.
 
 ## Answering questions with captures
 
@@ -119,9 +157,10 @@ not cached yet.
   work, and `ls --date` over a wide range walks many pages.
 - OCR text is noisy: it comes from screenshots at whatever resolution, and
   `locale` is often `und`. Treat it as a hint, not a transcript.
-- `get --objects` prints detected objects, but the API no longer returns the
-  field it reads, so it exits non-zero with "Object annotations not found" on
-  every capture tested. Use the OCR text instead.
+- `get --objects` prints what was detected in the image, with a confidence.
+  About 59% of captures carry annotations; the rest exit non-zero with "Object
+  annotations not found", which means this capture has none, not that the
+  command is broken. `--ocr` and `--objects` cannot be combined.
 - **Do not turn a capture into a claim it does not support.** A product page or
   a cart is interest; an order confirmation or a payment receipt is a purchase.
   Say which capture the conclusion rests on.