Orgman CLI

Command-line access to Orgman tasks, for terminal users and coding agents. You sign in as your normal Orgman user, and the CLI follows the same task visibility and permission rules as the web app.

Install

Requires Node 22 or newer.

npm install -g @magnet-software-development/orgman-cli
orgman auth login
orgman whoami

To update: npm install -g @magnet-software-development/orgman-cli@latest.

Signing in

orgman auth login opens Orgman in your browser. If you are already signed in there, you only need to approve the CLI. No tokens are copied by hand, and ordinary commands never open a browser on their own.

On a headless machine, sign in with a one-time code instead. The CLI does this by default over SSH and on Linux machines with no display:

$ orgman auth login --device
To sign in to production, open https://clerk.orgman.magnetdev.io/oauth/device and enter:

    WDJB-MJHT

Waiting for approval…

Open the URL on any device, enter the code, and approve. Use --browser to force the browser flow anyway. With --no-browser, the CLI prints the authorization URL instead of opening it; if the browser is on another device and the redirect back fails, paste the address of the failed page into the terminal to finish.

On macOS, credentials are stored in the Keychain. On other systems, they go in a file only your user can read, under ~/.config/orgman/.

orgman auth status
orgman doctor          # check connectivity and sign-in
orgman auth logout

Organizations

If you belong to several organizations, choose which one the CLI works in:

orgman org list                    # * marks the current organization
orgman org switch "Magnet Software" --yes
orgman whoami

The choice belongs to your account, so every CLI session on every machine switches together. Writes to production need --yes, and this is one.

To run a single command in another organization without switching anything, pass --org, or set ORGMAN_ORG for a whole shell or agent session. --org wins over ORGMAN_ORG, which wins over the switched organization:

orgman --org "Magnet Development" task get OM-abc123
ORGMAN_ORG="Magnet Development" orgman task comments add OM-abc123 --text "Done" --yes

It takes the same names and ids as org switch, and JSON output names the organization in meta.organization. Other sessions are not affected. A deployment from before --org rejects the request: the CLI reports CONFIG when validation details are available, or BACKEND when production hides them. Deploy the updated backend first. Agents must not work around a failure with org switch unless asked, since it moves every session.

Working with tasks

orgman task find "quarterly report"
orgman task get OM-abc123
orgman task list --status Ready --limit 25
orgman task create --title "Prepare report" --status Todo --type Task
orgman task update OM-abc123 --priority high --dry-run
orgman task status OM-abc123 Done
orgman task assign OM-abc123 [email protected]
orgman task comments add OM-abc123 --text "Plan approved"
orgman task open OM-abc123             # open in the browser

Tasks can be referenced by task code (OM-abc123) or numeric identifier. Destructive operations ask for --yes, and changes can be previewed with --dry-run. Run orgman help or orgman <command> --help for every command and flag.

Output

In a terminal, the CLI prints compact tables. When output is piped, it prints a stable JSON envelope, so scripts and agents can parse it. Force a format with --json or --output human|json|markdown. orgman task get OM-abc123 --output markdown exports a task with its context for pasting into notes or an agent prompt.

Coding agents

The package ships an agent skill that teaches Claude Code (and other agents that read SKILL.md skills) how to drive the CLI safely: targets, dry runs, the JSON envelope and error codes.

orgman skill install             # ~/.claude/skills/orgman-cli, for every project
orgman skill install --project   # ./.claude/skills, for this project only
orgman skill install --dir ~/.agents/skills   # another agent's skills directory

The skill matches the CLI version it came with, so run orgman skill install again after upgrading.

Shell completions

orgman completion zsh > "${fpath[1]}/_orgman"
orgman completion bash > /usr/local/etc/bash_completion.d/orgman
orgman completion fish > ~/.config/fish/completions/orgman.fish