Skip to main content

new

Preview
This feature is in preview and is subject to change.

Two commands cover the whole flow: motherduck new creates an account and organization, and motherduck new claim hands that organization to a real identity before it expires.

Usage​

motherduck new [options]
motherduck new claim [options]

motherduck new​

Creates a MotherDuck account and organization on the Free Plan, with no browser and no signup form. A MotherDuck token is returned and saved to ${MOTHERDUCK_HOME:-~/.motherduck}/credentials.json; every command after is authenticated.

The organization is separate from any account you already have, and stays ownerless until someone opens the claim URL and signs up.

warning

An unclaimed organization lapses 72 hours after it's created, and its data goes with it. Claim it to keep anything you build.

Options​

OptionDescription
--forceReplace the login credentials and any unclaimed organization
--region <region>AWS region for the new organization, for example aws-eu-central-1. Defaults to aws-us-east-1

A new organization means a new token, and the CLI holds one set of credentials, so the command refuses to run when you're already signed in. Sign out first, or overwrite deliberately with --force. Note that --force does not override MOTHERDUCK_TOKEN: unset that variable first.

--region does not default to your location. See cloud regions for which regions are available, prefixed with aws-.

Examples​

motherduck new
motherduck new --region aws-eu-central-1
motherduck logout && motherduck new
motherduck new --force
motherduck new -o json

Output​

Reports the region the organization was created in, that the new token is now your login credentials, and the claim URL with how long it stays valid.

motherduck new claim​

Claiming transfers the organization, and everything in it, to a real MotherDuck identity, and starts a 7-day Business plan trial. When that trial ends the organization continues on the Free Plan.

Open the URL motherduck new printed, or bring it back up:

motherduck new claim

In table output this also opens the URL in a browser, on a host that has one. With -o json or -o csv it prints the URL and expiry without opening anything, which is what a script or an agent wants.

While the window is open, motherduck status carries the same information.

warning

The token motherduck new saves grants read and write access to the account it created. Anyone who can read your credentials file can reach that data.

When to use it, and when to sign up instead​

The account motherduck new creates isn't tied to a person, and it's temporary until claimed. That makes it right for some situations and wrong for others.

Sign up, then run motherduck login, when:

  • You're joining an organization that already exists, where you want an invitation rather than a new organization of your own.
  • The account is yours and meant to last, tied to your email from the start.
  • You need billing, teammates, or a paid plan from the beginning.

Use motherduck new when:

  • An AI agent is working on someone's behalf and has no credentials to start from. See working with agents.
  • A CI job or sandbox needs a throwaway account for the length of a run.
  • You want to try MotherDuck immediately without stopping to fill in a form, and you'll claim it if the work turns out to be worth keeping.