ticktick-cli 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,187 @@
+# TickTick CLI
+
+A simple TypeScript CLI wrapper for the TickTick Open API documented at:
+
+- https://developer.ticktick.com/
+- https://developer.ticktick.com/docs#/openapi
+
+This wrapper covers the documented OAuth flow plus every documented task and project endpoint.
+
+## What it covers
+
+- OAuth authorization code flow
+- OAuth authorize URL generation
+- Get, create, update, complete, delete, move, list-completed, and filter task endpoints
+- List, get, create, update, delete, and get-data project endpoints
+- Raw authenticated request passthrough
+- Local config storage for client credentials and access tokens
+- `ticktick` and `dida365` service profiles, with manual base URL overrides when needed
+
+## Install
+
+```bash
+npm install
+npm run build
+```
+
+Run locally with:
+
+```bash
+node dist/cli.js --help
+```
+
+Or install the built CLI globally from this directory:
+
+```bash
+npm install -g .
+ticktick --help
+```
+
+## Configure
+
+The CLI reads config in this order:
+
+1. Command flags
+2. Environment variables
+3. Local config file
+4. Built-in defaults
+
+Useful environment variables:
+
+```bash
+TICKTICK_SERVICE=ticktick
+TICKTICK_CLIENT_ID=...
+TICKTICK_CLIENT_SECRET=...
+TICKTICK_REDIRECT_URI=http://127.0.0.1:18463/callback
+TICKTICK_SCOPES="tasks:read tasks:write"
+TICKTICK_ACCESS_TOKEN=...
+TICKTICK_API_BASE_URL=https://api.ticktick.com
+TICKTICK_AUTH_BASE_URL=https://ticktick.com
+TICKTICK_CONFIG_FILE=/custom/path/config.json
+```
+
+You can also persist config values:
+
+```bash
+ticktick config set clientId YOUR_CLIENT_ID
+ticktick config set clientSecret YOUR_CLIENT_SECRET
+ticktick config set redirectUri http://127.0.0.1:18463/callback
+ticktick config show
+```
+
+## Auth
+
+Interactive login:
+
+```bash
+ticktick auth login
+```
+
+If you already have an authorization code:
+
+```bash
+ticktick auth exchange YOUR_CODE
+```
+
+Print the authorize URL without starting the callback server:
+
+```bash
+ticktick auth url
+```
+
+Check current auth state:
+
+```bash
+ticktick auth status
+```
+
+Clear the stored access token:
+
+```bash
+ticktick auth logout
+```
+
+## Examples
+
+List projects:
+
+```bash
+ticktick project list
+```
+
+Get project details:
+
+```bash
+ticktick project get 6226ff9877acee87727f6bca
+ticktick project data 6226ff9877acee87727f6bca
+```
+
+Create a project:
+
+```bash
+ticktick project create --name "Inbox" --color "#F18181" --view-mode list --kind TASK
+```
+
+Create a task:
+
+```bash
+ticktick task create --project-id 6226ff9877acee87727f6bca --title "Ship CLI"
+```
+
+Update a task:
+
+```bash
+ticktick task update 63b7bebb91c0a5474805fcd4 --project-id 6226ff9877acee87727f6bca --priority 3
+```
+
+Move one task:
+
+```bash
+ticktick task move \
+  --from-project-id 69a850ef1c20d2030e148fdd \
+  --to-project-id 69a850f41c20d2030e148fdf \
+  --task-id 69a850f8b9061f374d54a046
+```
+
+Filter tasks using JSON:
+
+```bash
+ticktick task filter --json '{
+  "projectIds": ["69a850f41c20d2030e148fdf"],
+  "startDate": "2026-03-01T00:58:20.000+0000",
+  "endDate": "2026-03-06T10:58:20.000+0000",
+  "priority": [0],
+  "tag": ["urgent"],
+  "status": [0]
+}'
+```
+
+Move multiple tasks from a file:
+
+```bash
+ticktick task move --json-file ./moves.json
+```
+
+Pipe JSON into a command:
+
+```bash
+echo '{"name":"Planning","kind":"TASK"}' | ticktick project create
+```
+
+Send a raw authenticated request:
+
+```bash
+ticktick request GET /open/v1/project
+```
+
+Send a raw request to a full URL without bearer auth:
+
+```bash
+ticktick request POST https://httpbin.org/post --no-auth --json '{"hello":"world"}'
+```
+
+## Notes
+
+- The docs currently show `api.ticktick.com` for most endpoints, but `api.dida365.com` in the examples for `task/move`, `task/completed`, and `task/filter`. This CLI defaults to the selected service profile and lets you override base URLs explicitly if your account needs something different.
+- The CLI writes config to a local JSON file under the OS-specific app config directory unless `--config-file` or `TICKTICK_CONFIG_FILE` is set.
+- Access tokens and client secrets are stored as plain text in that config file. That keeps the wrapper simple, but it is not a secure keychain integration.

package/dist/auth.js

@@ -0,0 +1,110 @@
+import { createServer } from "node:http";
+import { randomUUID } from "node:crypto";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+export function buildAuthorizationUrl(config, state = randomUUID()) {
+    const url = new URL("/oauth/authorize", config.authBaseUrl);
+    url.searchParams.set("scope", config.scopes);
+    url.searchParams.set("client_id", config.clientId ?? "");
+    url.searchParams.set("state", state);
+    url.searchParams.set("redirect_uri", config.redirectUri ?? "");
+    url.searchParams.set("response_type", "code");
+    return { url: url.toString(), state };
+}
+export async function exchangeAuthorizationCode(config, code, fetchImpl = fetch) {
+    if (!config.clientId || !config.clientSecret) {
+        throw new Error("Client credentials are required. Provide them with flags, env vars, or `ticktick config set`.");
+    }
+    const tokenUrl = new URL("/oauth/token", config.authBaseUrl);
+    const params = new URLSearchParams({
+        grant_type: "authorization_code",
+        code,
+        scope: config.scopes,
+        redirect_uri: config.redirectUri ?? "",
+    });
+    const response = await fetchImpl(tokenUrl, {
+        method: "POST",
+        headers: {
+            Authorization: `Basic ${Buffer.from(`${config.clientId}:${config.clientSecret}`).toString("base64")}`,
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: params,
+    });
+    const raw = await response.text();
+    const parsed = raw.length > 0 ? JSON.parse(raw) : {};
+    if (!response.ok) {
+        throw new Error(`Token exchange failed with status ${response.status}: ${JSON.stringify(parsed)}`);
+    }
+    return parsed;
+}
+export function isLoopbackRedirect(redirectUri) {
+    if (!redirectUri) {
+        return false;
+    }
+    const parsed = new URL(redirectUri);
+    return (parsed.protocol === "http:" &&
+        ["127.0.0.1", "localhost"].includes(parsed.hostname));
+}
+export async function waitForOAuthCode(redirectUri, expectedState, timeoutMs = 120_000) {
+    const redirect = new URL(redirectUri);
+    const hostname = redirect.hostname === "localhost" ? "127.0.0.1" : redirect.hostname;
+    const port = Number.parseInt(redirect.port || "80", 10);
+    const callbackPath = redirect.pathname || "/";
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            server.close();
+            reject(new Error("Timed out waiting for the OAuth callback."));
+        }, timeoutMs);
+        const server = createServer((request, response) => {
+            const requestUrl = new URL(request.url ?? "/", redirect.origin);
+            if (requestUrl.pathname !== callbackPath) {
+                response.statusCode = 404;
+                response.end("Not Found");
+                return;
+            }
+            const code = requestUrl.searchParams.get("code");
+            const state = requestUrl.searchParams.get("state");
+            if (!code) {
+                response.statusCode = 400;
+                response.end("Missing authorization code.");
+                return;
+            }
+            if (state !== expectedState) {
+                response.statusCode = 400;
+                response.end("State mismatch.");
+                clearTimeout(timeout);
+                server.close();
+                reject(new Error("OAuth state mismatch."));
+                return;
+            }
+            response.setHeader("Content-Type", "text/html; charset=utf-8");
+            response.end("<html><body><h1>TickTick CLI</h1><p>Authorization complete. You can close this window.</p></body></html>");
+            clearTimeout(timeout);
+            server.close();
+            resolve(code);
+        });
+        server.on("error", (error) => {
+            clearTimeout(timeout);
+            reject(error);
+        });
+        server.listen(port, hostname);
+    });
+}
+export async function openBrowser(url) {
+    try {
+        if (process.platform === "win32") {
+            await execFileAsync("cmd", ["/c", "start", "", url]);
+            return;
+        }
+        if (process.platform === "darwin") {
+            await execFileAsync("open", [url]);
+            return;
+        }
+        await execFileAsync("xdg-open", [url]);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`Could not open a browser automatically: ${message}\n`);
+    }
+}

package/dist/cli.js

@@ -0,0 +1,490 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { buildAuthorizationUrl, exchangeAuthorizationCode, isLoopbackRedirect, openBrowser, waitForOAuthCode, } from "./auth.js";
+import { TickTickClient } from "./client.js";
+import { loadStoredConfig, resolveRuntimeConfig, saveStoredConfig, validateService, } from "./config.js";
+import { loadJsonValue, maskSecret, mergeDefined, parseBoolean, parseInteger, printJson, } from "./utils.js";
+const CONFIG_KEYS = new Set([
+    "service",
+    "clientId",
+    "clientSecret",
+    "redirectUri",
+    "scopes",
+    "accessToken",
+    "apiBaseUrl",
+    "authBaseUrl",
+]);
+const program = new Command();
+program
+    .name("ticktick")
+    .description("Simple CLI wrapper for the TickTick Open API")
+    .option("--config-file <path>", "Custom config file path")
+    .option("--service <service>", 'Service: "ticktick" or "dida365"')
+    .option("--api-base-url <url>", "Override the API base URL")
+    .option("--auth-base-url <url>", "Override the OAuth base URL")
+    .option("--access-token <token>", "Override the access token for a single command")
+    .option("--client-id <id>", "Override the OAuth client id")
+    .option("--client-secret <secret>", "Override the OAuth client secret")
+    .option("--redirect-uri <uri>", "Override the OAuth redirect URI")
+    .option("--scopes <scopes>", "Override the OAuth scopes");
+buildAuthCommands(program);
+buildConfigCommands(program);
+buildTaskCommands(program);
+buildProjectCommands(program);
+buildRequestCommand(program);
+program.parseAsync(process.argv).catch(handleError);
+function buildAuthCommands(root) {
+    const auth = root.command("auth").description("OAuth and token management");
+    auth
+        .command("url")
+        .description("Print the OAuth authorize URL without opening a browser")
+        .option("--state <value>", "Override the OAuth state value")
+        .action(async (...args) => {
+        const command = args.at(-1);
+        const options = command.optsWithGlobals();
+        const config = await resolveRuntimeConfig(runtimeOverrides(options));
+        requireClientId(config);
+        const result = buildAuthorizationUrl(config, options.state);
+        printJson(result);
+    });
+    auth
+        .command("login")
+        .description("Open the OAuth flow, exchange the code, and store the access token")
+        .option("--timeout-ms <number>", "Timeout while waiting for the callback", parseInteger, 120000)
+        .action(async (...args) => {
+        const command = args.at(-1);
+        const options = command.optsWithGlobals();
+        const config = await resolveRuntimeConfig(runtimeOverrides(options));
+        requireClientCredentials(config);
+        const { url, state } = buildAuthorizationUrl(config);
+        process.stderr.write(`Authorize URL:\n${url}\n`);
+        if (!isLoopbackRedirect(config.redirectUri)) {
+            printJson({
+                ok: false,
+                reason: "redirect_uri is not a local HTTP callback. Open the URL above and then run `ticktick auth exchange <code>`.",
+            });
+            return;
+        }
+        const codePromise = waitForOAuthCode(config.redirectUri, state, options.timeoutMs);
+        await openBrowser(url);
+        const code = await codePromise;
+        const token = await exchangeAuthorizationCode(config, code);
+        await persistConfig(config, token.access_token);
+        printJson(token);
+    });
+    auth
+        .command("exchange <code>")
+        .description("Exchange an authorization code for an access token")
+        .action(async (...args) => {
+        const command = args.at(-1);
+        const [code] = args;
+        const config = await resolveRuntimeConfig(runtimeOverrides(command.optsWithGlobals()));
+        requireClientCredentials(config);
+        const token = await exchangeAuthorizationCode(config, code);
+        await persistConfig(config, token.access_token);
+        printJson(token);
+    });
+    auth
+        .command("status")
+        .description("Show the resolved auth configuration")
+        .option("--show-secrets", "Include client secret and access token")
+        .action(async (...args) => {
+        const command = args.at(-1);
+        const options = command.optsWithGlobals();
+        const config = await resolveRuntimeConfig(runtimeOverrides(options));
+        printJson({
+            service: config.service,
+            configFile: config.configFile,
+            clientId: config.clientId,
+            clientSecret: options.showSecrets ? config.clientSecret : maskSecret(config.clientSecret),
+            redirectUri: config.redirectUri,
+            scopes: config.scopes,
+            accessToken: options.showSecrets ? config.accessToken : maskSecret(config.accessToken),
+            apiBaseUrl: config.apiBaseUrl,
+            authBaseUrl: config.authBaseUrl,
+        });
+    });
+    auth
+        .command("logout")
+        .description("Remove the stored access token from the config file")
+        .action(async (...args) => {
+        const command = args.at(-1);
+        const config = await resolveRuntimeConfig(runtimeOverrides(command.optsWithGlobals()));
+        const stored = await loadStoredConfig(config.configFile);
+        delete stored.accessToken;
+        await saveStoredConfig(config.configFile, stored);
+        printJson({ ok: true });
+    });
+}
+function buildConfigCommands(root) {
+    const config = root.command("config").description("Read and write local CLI config");
+    config
+        .command("show")
+        .description("Show the resolved configuration")
+        .option("--show-secrets", "Include stored secrets")
+        .action(async (...args) => {
+        const command = args.at(-1);
+        const options = command.optsWithGlobals();
+        const resolved = await resolveRuntimeConfig(runtimeOverrides(options));
+        printJson({
+            service: resolved.service,
+            configFile: resolved.configFile,
+            clientId: resolved.clientId,
+            clientSecret: options.showSecrets ? resolved.clientSecret : maskSecret(resolved.clientSecret),
+            redirectUri: resolved.redirectUri,
+            scopes: resolved.scopes,
+            accessToken: options.showSecrets ? resolved.accessToken : maskSecret(resolved.accessToken),
+            apiBaseUrl: resolved.apiBaseUrl,
+            authBaseUrl: resolved.authBaseUrl,
+        });
+    });
+    config
+        .command("set <key> <value>")
+        .description("Set a config value in the local config file")
+        .action(async (...args) => {
+        const command = args.at(-1);
+        const [key, value] = args;
+        const runtime = await resolveRuntimeConfig(runtimeOverrides(command.optsWithGlobals()));
+        if (!CONFIG_KEYS.has(key)) {
+            throw new Error(`Unsupported config key "${key}". Allowed keys: ${Array.from(CONFIG_KEYS).join(", ")}`);
+        }
+        const stored = await loadStoredConfig(runtime.configFile);
+        const normalizedValue = key === "service" ? validateService(value) : value;
+        const next = { ...stored, [key]: normalizedValue };
+        await saveStoredConfig(runtime.configFile, next);
+        printJson(next);
+    });
+    config
+        .command("unset <key>")
+        .description("Remove a config value from the local config file")
+        .action(async (...args) => {
+        const command = args.at(-1);
+        const [key] = args;
+        const runtime = await resolveRuntimeConfig(runtimeOverrides(command.optsWithGlobals()));
+        if (!CONFIG_KEYS.has(key)) {
+            throw new Error(`Unsupported config key "${key}". Allowed keys: ${Array.from(CONFIG_KEYS).join(", ")}`);
+        }
+        const stored = await loadStoredConfig(runtime.configFile);
+        delete stored[key];
+        await saveStoredConfig(runtime.configFile, stored);
+        printJson(stored);
+    });
+}
+function buildTaskCommands(root) {
+    const task = root.command("task").description("Task endpoints");
+    task
+        .command("get <projectId> <taskId>")
+        .description("Get a task by project id and task id")
+        .action(async (...args) => {
+        const [projectId, taskId] = args;
+        await runClientCommand(args, (client) => client.getTask(projectId, taskId));
+    });
+    withJsonBody(task
+        .command("create")
+        .description("Create a task")
+        .option("--project-id <id>", "Project id")
+        .option("--title <title>", "Task title")
+        .option("--content <content>", "Task content")
+        .option("--desc <desc>", "Task description")
+        .option("--start-date <date>", "Start date in yyyy-MM-dd'T'HH:mm:ssZ format")
+        .option("--due-date <date>", "Due date in yyyy-MM-dd'T'HH:mm:ssZ format")
+        .option("--time-zone <tz>", "Time zone")
+        .option("--repeat-flag <rrule>", "Recurring rule")
+        .option("--priority <number>", "Priority", parseInteger)
+        .option("--sort-order <number>", "Sort order", parseInteger)
+        .option("--all-day <boolean>", "All day", parseBoolean)).action(async (...args) => {
+        const command = args.at(-1);
+        const options = command.optsWithGlobals();
+        const payload = (await loadObjectPayload(options, {
+            projectId: options.projectId,
+            title: options.title,
+            content: options.content,
+            desc: options.desc,
+            startDate: options.startDate,
+            dueDate: options.dueDate,
+            timeZone: options.timeZone,
+            repeatFlag: options.repeatFlag,
+            priority: options.priority,
+            sortOrder: options.sortOrder,
+            isAllDay: options.allDay,
+        }));
+        if (!payload.projectId || !payload.title) {
+            throw new Error("Task creation requires both projectId and title.");
+        }
+        await runClientCommand(args, (client) => client.createTask(payload));
+    });
+    withJsonBody(task
+        .command("update <taskId>")
+        .description("Update a task")
+        .option("--project-id <id>", "Project id")
+        .option("--title <title>", "Task title")
+        .option("--content <content>", "Task content")
+        .option("--desc <desc>", "Task description")
+        .option("--start-date <date>", "Start date in yyyy-MM-dd'T'HH:mm:ssZ format")
+        .option("--due-date <date>", "Due date in yyyy-MM-dd'T'HH:mm:ssZ format")
+        .option("--time-zone <tz>", "Time zone")
+        .option("--repeat-flag <rrule>", "Recurring rule")
+        .option("--priority <number>", "Priority", parseInteger)
+        .option("--sort-order <number>", "Sort order", parseInteger)
+        .option("--all-day <boolean>", "All day", parseBoolean)).action(async (...args) => {
+        const command = args.at(-1);
+        const [taskId] = args;
+        const options = command.optsWithGlobals();
+        const payload = (await loadObjectPayload(options, {
+            id: taskId,
+            projectId: options.projectId,
+            title: options.title,
+            content: options.content,
+            desc: options.desc,
+            startDate: options.startDate,
+            dueDate: options.dueDate,
+            timeZone: options.timeZone,
+            repeatFlag: options.repeatFlag,
+            priority: options.priority,
+            sortOrder: options.sortOrder,
+            isAllDay: options.allDay,
+        }));
+        payload.id = taskId;
+        if (!payload.projectId) {
+            throw new Error("Task update requires projectId.");
+        }
+        await runClientCommand(args, (client) => client.updateTask(taskId, payload));
+    });
+    task
+        .command("complete <projectId> <taskId>")
+        .description("Complete a task")
+        .action(async (...args) => {
+        const [projectId, taskId] = args;
+        await runClientCommand(args, (client) => client.completeTask(projectId, taskId));
+    });
+    task
+        .command("delete <projectId> <taskId>")
+        .description("Delete a task")
+        .action(async (...args) => {
+        const [projectId, taskId] = args;
+        await runClientCommand(args, (client) => client.deleteTask(projectId, taskId));
+    });
+    withJsonBody(task
+        .command("move")
+        .description("Move one or more tasks between projects")
+        .option("--from-project-id <id>", "Source project id")
+        .option("--to-project-id <id>", "Destination project id")
+        .option("--task-id <id>", "Task id")).action(async (...args) => {
+        const command = args.at(-1);
+        const options = command.optsWithGlobals();
+        let payload = (await loadJsonValue(options.json, options.jsonFile));
+        if (!payload) {
+            if (!options.fromProjectId || !options.toProjectId || !options.taskId) {
+                throw new Error("Provide --json/--json-file or all of --from-project-id, --to-project-id, and --task-id.");
+            }
+            payload = [
+                {
+                    fromProjectId: options.fromProjectId,
+                    toProjectId: options.toProjectId,
+                    taskId: options.taskId,
+                },
+            ];
+        }
+        if (!Array.isArray(payload)) {
+            throw new Error("Move payload must be a JSON array.");
+        }
+        await runClientCommand(args, (client) => client.moveTasks(payload));
+    });
+    withJsonBody(task
+        .command("completed")
+        .description("List completed tasks")
+        .option("--project-id <id>", "Project id", collectString, [])
+        .option("--start-date <date>", "Start of completedTime range")
+        .option("--end-date <date>", "End of completedTime range")).action(async (...args) => {
+        const command = args.at(-1);
+        const options = command.optsWithGlobals();
+        const payload = (await loadObjectPayload(options, {
+            projectIds: options.projectId && options.projectId.length > 0 ? options.projectId : undefined,
+            startDate: options.startDate,
+            endDate: options.endDate,
+        }));
+        await runClientCommand(args, (client) => client.listCompletedTasks(payload));
+    });
+    withJsonBody(task
+        .command("filter")
+        .description("Filter tasks")
+        .option("--project-id <id>", "Project id", collectString, [])
+        .option("--start-date <date>", "Start date lower bound")
+        .option("--end-date <date>", "Start date upper bound")
+        .option("--priority <number>", "Priority filter", collectInteger, [])
+        .option("--tag <tag>", "Tag filter", collectString, [])
+        .option("--status <number>", "Status filter", collectInteger, [])).action(async (...args) => {
+        const command = args.at(-1);
+        const options = command.optsWithGlobals();
+        const payload = (await loadObjectPayload(options, {
+            projectIds: options.projectId && options.projectId.length > 0 ? options.projectId : undefined,
+            startDate: options.startDate,
+            endDate: options.endDate,
+            priority: options.priority && options.priority.length > 0 ? options.priority : undefined,
+            tag: options.tag && options.tag.length > 0 ? options.tag : undefined,
+            status: options.status && options.status.length > 0 ? options.status : undefined,
+        }));
+        await runClientCommand(args, (client) => client.filterTasks(payload));
+    });
+}
+function buildProjectCommands(root) {
+    const project = root.command("project").description("Project endpoints");
+    project
+        .command("list")
+        .description("List user projects")
+        .action(async (...args) => {
+        await runClientCommand(args, (client) => client.listProjects());
+    });
+    project
+        .command("get <projectId>")
+        .description("Get a project by id")
+        .action(async (...args) => {
+        const [projectId] = args;
+        await runClientCommand(args, (client) => client.getProject(projectId));
+    });
+    project
+        .command("data <projectId>")
+        .description("Get a project together with tasks and columns")
+        .action(async (...args) => {
+        const [projectId] = args;
+        await runClientCommand(args, (client) => client.getProjectData(projectId));
+    });
+    withJsonBody(project
+        .command("create")
+        .description("Create a project")
+        .option("--name <name>", "Project name")
+        .option("--color <color>", 'Project color, for example "#F18181"')
+        .option("--sort-order <number>", "Sort order", parseInteger)
+        .option("--view-mode <mode>", 'View mode: "list", "kanban", or "timeline"')
+        .option("--kind <kind>", 'Kind: "TASK" or "NOTE"')).action(async (...args) => {
+        const command = args.at(-1);
+        const options = command.optsWithGlobals();
+        const payload = (await loadObjectPayload(options, {
+            name: options.name,
+            color: options.color,
+            sortOrder: options.sortOrder,
+            viewMode: options.viewMode,
+            kind: options.kind,
+        }));
+        if (!payload.name) {
+            throw new Error("Project creation requires name.");
+        }
+        await runClientCommand(args, (client) => client.createProject(payload));
+    });
+    withJsonBody(project
+        .command("update <projectId>")
+        .description("Update a project")
+        .option("--name <name>", "Project name")
+        .option("--color <color>", 'Project color, for example "#F18181"')
+        .option("--sort-order <number>", "Sort order", parseInteger)
+        .option("--view-mode <mode>", 'View mode: "list", "kanban", or "timeline"')
+        .option("--kind <kind>", 'Kind: "TASK" or "NOTE"')).action(async (...args) => {
+        const command = args.at(-1);
+        const [projectId] = args;
+        const options = command.optsWithGlobals();
+        const payload = (await loadObjectPayload(options, {
+            name: options.name,
+            color: options.color,
+            sortOrder: options.sortOrder,
+            viewMode: options.viewMode,
+            kind: options.kind,
+        }));
+        await runClientCommand(args, (client) => client.updateProject(projectId, payload));
+    });
+    project
+        .command("delete <projectId>")
+        .description("Delete a project")
+        .action(async (...args) => {
+        const [projectId] = args;
+        await runClientCommand(args, (client) => client.deleteProject(projectId));
+    });
+}
+function buildRequestCommand(root) {
+    withJsonBody(root
+        .command("request <method> <path>")
+        .description("Send a raw request to the configured API base URL, or to a full URL")
+        .option("--no-auth", "Skip bearer auth on this request")).action(async (...args) => {
+        const command = args.at(-1);
+        const [method, path] = args;
+        const options = command.optsWithGlobals();
+        const config = await resolveRuntimeConfig(runtimeOverrides(options));
+        const client = new TickTickClient(config);
+        const body = await loadJsonValue(options.json, options.jsonFile);
+        const result = await client.requestRaw(method.toUpperCase(), path, body, { auth: options.auth });
+        printJson(result ?? { ok: true });
+    });
+}
+function withJsonBody(command) {
+    return command
+        .option("--json <json>", "Inline JSON body")
+        .option("--json-file <path>", "Path to a JSON body file");
+}
+function runtimeOverrides(options) {
+    return {
+        configFile: options.configFile,
+        service: options.service ? validateService(options.service) : undefined,
+        apiBaseUrl: options.apiBaseUrl,
+        authBaseUrl: options.authBaseUrl,
+        accessToken: options.accessToken,
+        clientId: options.clientId,
+        clientSecret: options.clientSecret,
+        redirectUri: options.redirectUri,
+        scopes: options.scopes,
+    };
+}
+async function runClientCommand(args, runner) {
+    const command = args.at(-1);
+    const config = await resolveRuntimeConfig(runtimeOverrides(command.optsWithGlobals()));
+    const client = new TickTickClient(config);
+    const result = await runner(client, config);
+    printJson(result ?? { ok: true });
+}
+async function loadObjectPayload(options, flags) {
+    const loaded = await loadJsonValue(options.json, options.jsonFile);
+    if (loaded === undefined) {
+        return mergeDefined({}, flags);
+    }
+    if (!isPlainObject(loaded)) {
+        throw new Error("Expected a JSON object payload.");
+    }
+    return mergeDefined(loaded, flags);
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function persistConfig(runtime, accessToken) {
+    const stored = await loadStoredConfig(runtime.configFile);
+    const next = {
+        ...stored,
+        service: runtime.service,
+        clientId: runtime.clientId,
+        clientSecret: runtime.clientSecret,
+        redirectUri: runtime.redirectUri,
+        scopes: runtime.scopes,
+        apiBaseUrl: runtime.apiBaseUrl,
+        authBaseUrl: runtime.authBaseUrl,
+        accessToken,
+    };
+    await saveStoredConfig(runtime.configFile, next);
+}
+function requireClientCredentials(config) {
+    if (!config.clientId || !config.clientSecret) {
+        throw new Error("Client credentials are required. Set TICKTICK_CLIENT_ID and TICKTICK_CLIENT_SECRET or use `ticktick config set`.");
+    }
+}
+function requireClientId(config) {
+    if (!config.clientId) {
+        throw new Error("Client id is required. Set TICKTICK_CLIENT_ID or use `ticktick config set clientId ...`.");
+    }
+}
+function collectString(value, previous = []) {
+    return [...previous, value];
+}
+function collectInteger(value, previous = []) {
+    return [...previous, parseInteger(value)];
+}
+function handleError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${message}\n`);
+    process.exitCode = 1;
+}

package/dist/client.js

@@ -0,0 +1,101 @@
+export class TickTickApiError extends Error {
+    status;
+    payload;
+    constructor(status, payload) {
+        const summary = typeof payload === "string"
+            ? payload
+            : payload
+                ? JSON.stringify(payload)
+                : "No response body";
+        super(`TickTick API request failed with status ${status}: ${summary}`);
+        this.name = "TickTickApiError";
+        this.status = status;
+        this.payload = payload;
+    }
+}
+export class TickTickClient {
+    config;
+    fetchImpl;
+    constructor(config, fetchImpl = fetch) {
+        this.config = config;
+        this.fetchImpl = fetchImpl;
+    }
+    async requestRaw(method, pathOrUrl, body, options = {}) {
+        const requiresAuth = options.auth ?? true;
+        if (requiresAuth && !this.config.accessToken) {
+            throw new Error("No access token available. Run `ticktick auth login` or provide TICKTICK_ACCESS_TOKEN.");
+        }
+        const url = /^https?:\/\//.test(pathOrUrl)
+            ? pathOrUrl
+            : `${this.config.apiBaseUrl}${pathOrUrl}`;
+        const response = await this.fetchImpl(url, {
+            method,
+            headers: {
+                ...(requiresAuth
+                    ? { Authorization: `Bearer ${this.config.accessToken}` }
+                    : {}),
+                ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+            },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        if (response.status === 204) {
+            return undefined;
+        }
+        const raw = await response.text();
+        const parsed = raw.length > 0 ? tryParseJson(raw) : undefined;
+        if (!response.ok) {
+            throw new TickTickApiError(response.status, parsed ?? raw);
+        }
+        return parsed;
+    }
+    getTask(projectId, taskId) {
+        return this.requestRaw("GET", `/open/v1/project/${projectId}/task/${taskId}`);
+    }
+    createTask(payload) {
+        return this.requestRaw("POST", "/open/v1/task", payload);
+    }
+    updateTask(taskId, payload) {
+        return this.requestRaw("POST", `/open/v1/task/${taskId}`, payload);
+    }
+    completeTask(projectId, taskId) {
+        return this.requestRaw("POST", `/open/v1/project/${projectId}/task/${taskId}/complete`);
+    }
+    deleteTask(projectId, taskId) {
+        return this.requestRaw("DELETE", `/open/v1/project/${projectId}/task/${taskId}`);
+    }
+    moveTasks(payload) {
+        return this.requestRaw("POST", "/open/v1/task/move", payload);
+    }
+    listCompletedTasks(payload) {
+        return this.requestRaw("POST", "/open/v1/task/completed", payload);
+    }
+    filterTasks(payload) {
+        return this.requestRaw("POST", "/open/v1/task/filter", payload);
+    }
+    listProjects() {
+        return this.requestRaw("GET", "/open/v1/project");
+    }
+    getProject(projectId) {
+        return this.requestRaw("GET", `/open/v1/project/${projectId}`);
+    }
+    getProjectData(projectId) {
+        return this.requestRaw("GET", `/open/v1/project/${projectId}/data`);
+    }
+    createProject(payload) {
+        return this.requestRaw("POST", "/open/v1/project", payload);
+    }
+    updateProject(projectId, payload) {
+        return this.requestRaw("POST", `/open/v1/project/${projectId}`, payload);
+    }
+    deleteProject(projectId) {
+        return this.requestRaw("DELETE", `/open/v1/project/${projectId}`);
+    }
+}
+function tryParseJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}

package/dist/config.js

@@ -0,0 +1,85 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+const DEFAULT_SCOPES = "tasks:read tasks:write";
+const DEFAULT_SERVICE = "ticktick";
+const SERVICE_DEFAULTS = {
+    ticktick: {
+        apiBaseUrl: "https://api.ticktick.com",
+        authBaseUrl: "https://ticktick.com",
+    },
+    dida365: {
+        apiBaseUrl: "https://api.dida365.com",
+        authBaseUrl: "https://dida365.com",
+    },
+};
+export function defaultConfigFilePath() {
+    const appData = process.env.APPDATA;
+    if (process.platform === "win32" && appData) {
+        return path.join(appData, "ticktick-cli", "config.json");
+    }
+    if (process.platform === "darwin") {
+        return path.join(os.homedir(), "Library", "Application Support", "ticktick-cli", "config.json");
+    }
+    return path.join(os.homedir(), ".config", "ticktick-cli", "config.json");
+}
+export async function loadStoredConfig(configFile) {
+    try {
+        const raw = await readFile(configFile, "utf8");
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return {};
+        }
+        throw error;
+    }
+}
+export async function saveStoredConfig(configFile, config) {
+    await mkdir(path.dirname(configFile), { recursive: true });
+    await writeFile(configFile, JSON.stringify(config, null, 2), "utf8");
+}
+export function validateService(service) {
+    if (service === "ticktick" || service === "dida365") {
+        return service;
+    }
+    throw new Error(`Unsupported service "${service}". Use "ticktick" or "dida365".`);
+}
+function envConfig(env) {
+    return {
+        service: env.TICKTICK_SERVICE
+            ? validateService(env.TICKTICK_SERVICE)
+            : undefined,
+        clientId: env.TICKTICK_CLIENT_ID,
+        clientSecret: env.TICKTICK_CLIENT_SECRET,
+        redirectUri: env.TICKTICK_REDIRECT_URI,
+        scopes: env.TICKTICK_SCOPES,
+        accessToken: env.TICKTICK_ACCESS_TOKEN,
+        apiBaseUrl: env.TICKTICK_API_BASE_URL,
+        authBaseUrl: env.TICKTICK_AUTH_BASE_URL,
+    };
+}
+export async function resolveRuntimeConfig(overrides = {}, env = process.env) {
+    const configFile = overrides.configFile ?? env.TICKTICK_CONFIG_FILE ?? defaultConfigFilePath();
+    const stored = await loadStoredConfig(configFile);
+    const fromEnv = envConfig(env);
+    const service = overrides.service ?? fromEnv.service ?? stored.service ?? DEFAULT_SERVICE;
+    const defaults = SERVICE_DEFAULTS[service];
+    return {
+        service,
+        configFile,
+        clientId: overrides.clientId ?? fromEnv.clientId ?? stored.clientId,
+        clientSecret: overrides.clientSecret ?? fromEnv.clientSecret ?? stored.clientSecret,
+        redirectUri: overrides.redirectUri ??
+            fromEnv.redirectUri ??
+            stored.redirectUri ??
+            "http://127.0.0.1:18463/callback",
+        scopes: overrides.scopes ?? fromEnv.scopes ?? stored.scopes ?? DEFAULT_SCOPES,
+        accessToken: overrides.accessToken ?? fromEnv.accessToken ?? stored.accessToken,
+        apiBaseUrl: overrides.apiBaseUrl ?? fromEnv.apiBaseUrl ?? stored.apiBaseUrl ?? defaults.apiBaseUrl,
+        authBaseUrl: overrides.authBaseUrl ??
+            fromEnv.authBaseUrl ??
+            stored.authBaseUrl ??
+            defaults.authBaseUrl,
+    };
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.js

@@ -0,0 +1,69 @@
+import { readFile } from "node:fs/promises";
+export function mergeDefined(base, patch) {
+    const next = { ...base };
+    for (const [key, value] of Object.entries(patch)) {
+        if (value !== undefined) {
+            next[key] = value;
+        }
+    }
+    return next;
+}
+export function parseBoolean(value) {
+    const normalized = value.trim().toLowerCase();
+    if (["true", "1", "yes", "y"].includes(normalized)) {
+        return true;
+    }
+    if (["false", "0", "no", "n"].includes(normalized)) {
+        return false;
+    }
+    throw new Error(`Expected a boolean value, received "${value}".`);
+}
+export function parseInteger(value) {
+    const parsed = Number.parseInt(value, 10);
+    if (Number.isNaN(parsed)) {
+        throw new Error(`Expected an integer value, received "${value}".`);
+    }
+    return parsed;
+}
+export async function maybeReadStdin() {
+    if (process.stdin.isTTY) {
+        return undefined;
+    }
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    const text = Buffer.concat(chunks).toString("utf8").trim();
+    return text.length > 0 ? text : undefined;
+}
+export async function loadJsonValue(inlineJson, jsonFile) {
+    let raw = inlineJson;
+    if (jsonFile) {
+        raw = await readFile(jsonFile, "utf8");
+    }
+    if (!raw) {
+        raw = await maybeReadStdin();
+    }
+    if (!raw) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to parse JSON input: ${message}`);
+    }
+}
+export function printJson(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+export function maskSecret(value) {
+    if (!value) {
+        return value;
+    }
+    if (value.length <= 6) {
+        return "*".repeat(value.length);
+    }
+    return `${value.slice(0, 3)}***${value.slice(-3)}`;
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "ticktick-cli",
+  "version": "0.1.1",
+  "description": "Simple CLI wrapper for the TickTick Open API",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "ticktick": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "check": "npm run build",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "dev": "tsx src/cli.ts",
+    "prepack": "npm run test",
+    "test": "npm run build && node --import tsx --test src/test/*.test.ts"
+  },
+  "keywords": [
+    "ticktick",
+    "cli",
+    "oauth2",
+    "tasks",
+    "projects"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "commander": "^14.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.3"
+  }
+}