Skip to content
dotby Docs

Use the CLI

The dotby command puts your workspace in the terminal. Create a task without leaving the branch you are on, list what is assigned to you, or let a script do a hundred of those at once.

It is a thin client of the REST API: everything it can do, it does as you, with your permissions. There is no separate CLI account and no super-token.

Install

Section titled “Install”

The CLI ships as an npm package that carries the binary for your platform. There is no postinstall script, so it also installs under --ignore-scripts, which is what locked-down CI and agent sandboxes run.

Terminal window
npm i -g dotby-cli

The package is dotby-cli; the command it installs is dotby.

Sign in

Section titled “Sign in”

  1. On your machine, let it open the browser:

    Terminal window
    dotby auth login
    dotby auth status

    The session refreshes itself, and the credentials go to your system keychain — never into the repo.

  2. In a script, a CI job, or an agent, there is no browser. Create a personal access token in the app under Settings → API keys, then pipe it in:

    Terminal window
    printf %s "$DOTBY_PAT" | dotby auth login --with-token

    Setting DOTBY_TOKEN in the environment works too, and beats every stored credential.

Never pass a token as a flag value or an argument. It would land in your shell history and in the process list of every user on the machine.

Point it at a workspace

Section titled “Point it at a workspace”

Every command needs to know which workspace it is talking to, and most need a project. Answer that once per repo:

Terminal window
dotby init

It writes a .dotby.toml you commit, so your whole team inherits the same context:

workspace = "acme"
project = "ENG"

When you want to know what is actually in effect — and where each value came from — ask:

Terminal window
dotby context

Precedence runs --workspace flag → DOTBY_WORKSPACE → the nearest .dotby.toml → your user config. Anything you pass on the command line wins.

Everyday commands

Section titled “Everyday commands”

The grammar is at most two levels: a noun, then a verb. --help works on any of them.

Terminal window
dotby issue list --state-bucket started
dotby issue view ENG-42 --include description
dotby issue create --title "Fix login redirect" --priority high
dotby issue move ENG-42 --state <stateId>
dotby issue comment ENG-42 -b "Deployed to staging"
dotby search "login redirect"

A task is addressed the way you say it out loud: ENG-42. Projects go by their key (ENG), workspaces by their slug. Ids work everywhere too, for reads and writes alike.

Read it from a script

Section titled “Read it from a script”

Standard output carries data and nothing else — progress, hints, and errors all go to standard error, so a pipe never swallows something you needed to read.

Terminal window
dotby issue list --json=identifier,title,state   # pick your fields
dotby issue list --json                          # list the fields available
dotby issue list --jq '.[].identifier'           # filter in place

--jq runs in-process, so there is no jq binary to install first.

Inside CI or an agent — or any time output is piped — the CLI drops colors, stops truncating, and never prompts.

Rehearse a write

Section titled “Rehearse a write”

Every mutation takes --dry-run: it prints the request it would send, changes nothing, and exits 0. No network and no credentials needed, which makes it safe to run in a test.

Terminal window
dotby issue create --title "Fix login" --priority high --dry-run
dotby issue archive ENG-42 --yes

--yes skips confirmations. Destructive commands need it in any non-interactive session, because the CLI refuses to prompt where nobody can answer.

Exit codes

Section titled “Exit codes”
Code Meaning
0 Success
1 Something failed
2 Bad flags, missing arguments, or no workspace in context
3 The task, project, or workspace doesn’t exist
4 Not signed in, or the token was rejected

That is what makes the CLI scriptable: “create it if it isn’t there” is a case statement, not a string match.

Terminal window
dotby issue view "$KEY" --json= >/dev/null 2>&1
case $? in
  0) echo "exists" ;;
  3) dotby issue create --title "$TITLE" ;;
  4) echo "auth needed" >&2; exit 1 ;;
esac

With --json, a failure also prints a parseable envelope whose hint is the exact command that fixes it.

Create many at once

Section titled “Create many at once”

Feed one JSON object per line on standard input. The CLI batches them and streams a result per item, so a partial failure tells you exactly which line failed.

Terminal window
dotby bulk create --priority medium <<'EOF'
{"title":"Set up CI"}
{"title":"Fix login redirect","priority":1}
{"title":"Write onboarding doc"}
EOF

Everything else

Section titled “Everything else”

Commands cover the daily path. For the rest of the API — members, time entries, initiatives, pages, sprints — call it directly:

Terminal window
dotby api GET /me
dotby api GET '/workspaces/acme/issues/mine?tab=assigned'
echo '{"name":"Q3 launch"}' | dotby api POST /workspaces/acme/initiatives

Paths are rooted at /v1. Auth, retries, and error mapping still apply, so this is a shortcut, not a downgrade.