1Medium CLI (m1)

Automate your 1Medium workspace from the command-line.

✨ What the CLI lets you do

| Command | Purpose | | ---------------------------- | ---------------------------------------------------------------------------------- | | m1 login | Save an API token to ~/.m1rc (or %USERPROFILE%\.m1rc on Windows). | | m1 whoami | Show the first characters of the stored token so you know which account is in use. | | m1 script:push <file> | Upload versioned scripts to a Priority, Tag or whole Project. | | m1 script:list | List the latest version of every script that belongs to the current user. | | m1 script:test --task <id> | Dry-run a script against a single task (no data mutated). |

🔧 Installation

Get your API key on your Account Page

# clone or download the repo, then:
npm i -g .
# or use npx without installing globally
npx m1-cli <command>

The CLI has zero runtime dependencies beyond Node ≥ 18, Commander and Axios.

🗝 Authentication

1. Create a personal API token in Settings → Developer on the 1Medium web app.
2. Run:

m1 login
# You’ll be prompted to paste the token

Your token is stored in ~/.m1rc:

{
  "apiToken": "paf_1234567890abcdef"
}

🚀 Working with scripts

1. Create a script file

// examples/simple.js
/*
meta:
  trigger: onUpdate        # onUpdate | onTag | onCreate | schedule
  targetType: priority     # priority | tag | project
*/

/**
 * Logs a message every time its task is edited.
 */
function run () {
  task.log(`Task "${task.title}" was updated at ${new Date().toISOString()}`);
}

run();

💡 Metadata can be supplied in YAML-style comments or via CLI flags. If you omit a version, the backend will auto-increment it.

2. Push it

m1 script:push examples/simple.js \
  --target-id 39868d6e-d404-4563-84f4-27aab3299761 \
  --target-type priority \
  --trigger onUpdate

The server:

• Saves a new record in the Scripts table
• If a script with the same name + targetType + targetId exists, bumps version by 1.

You’ll see:

🔼 Uploading examples/simple.js…
✅ Uploaded: { name: 'simple.js', version: 3, … }

3. List your scripts

m1 script:list

┌────────────┬─────────┬───────────┬──────────┐
│ Name       │ Version │ Target    │ Trigger  │
├────────────┼─────────┼───────────┼──────────┤
│ simple.js  │ 3       │ priority  │ onUpdate │
│ sprint.js  │ 1       │ project   │ schedule │
└────────────┴─────────┴───────────┴──────────┘

🧪 Testing without side effects

m1 script:test --task 55b7c2c4-…-d8f2

The CLI posts to /scripts/test, the backend spins up the isolated-vm runtime and returns a diff of the operations it would perform.

📄 Environment variables & config

| Location | Purpose | | ------------- | -------------------------------------------------------------------------------------------------- | | ~/.m1rc | Stores { apiToken }. | | M1_API_ROOT | Override API root (defaults to prod). | | M1_EDITOR | If set, m1 script:push opens $EDITOR when upload fails validation so you can fix and resubmit. |

🛡 Runtime constraints

| Limit | Value | | ---------------- | --------------------------------------- | | Memory | 8 MB per script run | | CPU time | 500 ms (hard timeout) | | External network | Only HTTP → whitelisted domains | | Node globals | Not available (require, fs) | | Exposed objects | task, user, plus helpers you inject |

🤖 Writing scripts

Inside the sandbox you get:

declare const task: {
  title: string;
  description: string;
  dueDate: string | null;
  log(msg: string): void;
  addTag(tag: string): Promise<void>;
  comment(text: string): Promise<void>;
};

declare const user: { id: string; name: string; email: string };

Return values are ignored but logged in the backend; throw an Error to abort.

📝 Examples

/* meta:
     trigger: onTag
     targetType: tag
*/

// Fire when the tag “danger” is applied to any task
if (task.title && task.title.match(/urgent/i)) {
  task.log("🚨 Urgent task needs attention!");
  await task.comment("Automatic reminder: this task is tagged *danger*");
}

/* meta:
     trigger: schedule
     targetType: project
     cron: "0 9 * * 1-5"    # Weekdays at 09:00
*/

// Monday–Friday morning digest
const today = new Date().toLocaleDateString();
task.log(`Sending daily digest for ${today}`);

// call external webhook, etc.

🧹 Uninstall

npm uninstall -g m1-cli
rm ~/.m1rc           # optional

🙋 Need help?

Issues/PRs welcome → github.com/your-org/m1-cli Or ping @support in the 1Medium Slack.