DEV Community

Cover image for Day one to `dotvault pull` in five minutes
uehara
uehara

Posted on Edited on

Day one to `dotvault pull` in five minutes

This is part 12 of the series "dotvault, Start to Finish: One Command from Your Laptop to CI, Your Team, and Your AI Agents." Anyone can create a dotvault account and use it for free.

Part 1 of this series promised day one in five minutes. We timed a new teammate's first day on an empty machine. From installing the dotvault CLI to a finished dotvault pull took under 20 seconds. Ten of those went to npm. Logging in took two.

The teammate typed four commands. Everything else had been set up once, beforehand, by whoever runs the org, and that setup is what parts 1 to 11 of this series covered. This last part puts all of it on one page, shows the three failures a new teammate is most likely to hit, and shows what the free plan includes, from the screens themselves. Anyone can now create a dotvault account and use it for free.

This is part 12 of 12.

The short version

  • Anyone can sign up. Create an account at app.dotvault.io with an email address and a password.
  • An invited teammate needs four commands: install, login, init, pull. In the demo, that took under 20 seconds. With project-config.json committed to the repository, it is three.
  • The Company free plan covers 10 users, 25 projects, unlimited keys and 1,000 pulls a day.
  • Day-one failures are easy to tell apart by exit code: 4 for a missing grant or a mistyped project name, 3 for not being logged in.

Before you read on

This part sums up parts 1 to 11. You can follow it without them.

1. Under 20 seconds, command by command

The teammate is dev-d, invited in part 9 and given the reader role on one environment, development, of the project acme-shop. We pointed HOME at an empty folder so the machine looked brand new, and printed the time before every command.

Terminal, recomposed from real output. At 13:00:37 UTC, npm i -g @earthlink/dotvault. Ten seconds in, dotvault --version prints 0.19.1. At 11 seconds, dotvault login asks for Email and Password and prints "Logged in as <demo email>. Session valid until … (365 days); the access token refreshes automatically." At 13 seconds, whoami lists two orgs: Acme Shop (company, guest) and Personal (personal, org_admin). At 17 seconds, dotvault init --name acme-shop prints "Created project-config.json (project=acme-shop)." and dotvault pull prints "✓ Wrote 2 keys to /work/day1/acme-shop/.env (project=acme-shop, env=development, file=.env). Markers preserved." At 19 seconds, ls -l .env shows -rw-------, and the .env, cut to 24 characters per line, holds DATABASE_URL and STRIPE_SECRET_KEY between the BEGIN and END lines.

Elapsed Command What came back
0 s npm i -g @earthlink/dotvault The CLI installs (10 seconds)
11 s dotvault login Email and Password prompts, then "Logged in as …"
13 s dotvault whoami Two orgs: Acme Shop, which invited them, and their own Personal org
17 s dotvault init --name acme-shop project-config.json is created
17 s dotvault pull "Wrote 2 keys … env=development"
19 s ls -l .env -rw-------, readable by the owner only

The login line says the session is valid for 365 days and the access token refreshes automatically, so a teammate does not log in again every morning.

init only writes project-config.json, which links the folder to a project. Commit that file to the repository and a teammate who clones it skips init: install, login, pull (part 2).

A forgotten password is reset from "Forgot your password?" on the sign-in page.

2. Three day-one failures, by exit code

On the same machine, we triggered the three failures a new teammate is most likely to see.

Terminal, recomposed from real output. dotvault pull -E production, an environment dev-d was not given, prints "✖ PERMISSION_DENIED: You do not have permission for project 'acme-shop' env 'production' …" with exit code 4. dotvault pull acme-shopp, a mistyped project name, also prints PERMISSION_DENIED with exit code 4. After dotvault logout, dotvault pull prints "✖ AUTH_REQUIRED: Not logged in. Run  raw `dotvault login` endraw  first." with exit code 3.

Output Exit code Cause Fix
PERMISSION_DENIED (production) 4 An environment you were not given Ask an admin to grant it (part 9)
PERMISSION_DENIED (acme-shopp) 4 A mistyped project name Check the name (a name with capitals fails differently: BAD_PROJECT, exit code 1, part 2)
AUTH_REQUIRED: Not logged in 3 Not logged in Run dotvault login

A missing grant and a typo look the same: the message says "The project may not exist, or you may not have been granted access". Check the name first, then ask an admin. Other failures, such as NETWORK_ERROR, are covered in part 2.

3. Create an account

Open https://app.dotvault.io/signup. The "Start free" button on dotvault.io opens this screen too.

The dotvault sign-up screen. Heading: Create an account. Text: "Register with your email address and a password. We will email you a confirmation code." Three fields: Email address; Password (at least 12 characters, including upper and lower case, a digit and a symbol); Password (confirm). Below them, a red Create account button, and below the button the line "By signing up, you agree to the Terms of Service and the Privacy Policy." (Terms of Service and Privacy Policy are links). Outside this box is the link "Already have an account? Sign in".

The password needs at least 12 characters, with upper and lower case, a digit and a symbol. Create account takes you to the confirmation screen.

The confirmation screen. Heading: Confirm your email address. Text: "Enter the confirmation code from your email. Once confirmed you can sign in." Two fields: Email address, filled with an example address, and Confirmation code (the 6-digit number from the email). Below them, a red Confirm email button and the link "Resend the code".

The code arrives from dotvault with the subject "Verify your new account". We signed up a fresh account to check the rest: after Confirm email you are sent to the sign-in page, and on first sign-in the console opens on a page headed Personal, your own org. dotvault whoami lists that one org, Personal (personal, org_admin).

To work as a team, convert it to a Company org and invite people (part 9).

4. From day two, it is just pull

After day one, the only command a teammate needs is dotvault pull. When an admin changes a value in the console or with dotvault set, running dotvault pull again in the same folder replaces the block between the BEGIN and END lines in .env with the current values (parts 2 and 4). Lines you wrote yourself outside that block stay as they are.

If you would rather not write .env to disk at all, dotvault run -- npm run dev starts the process with the values in its environment (part 2).

Day one is four commands only because an admin did three things first:

Done beforehand What it means on day one Part
Invite by email and grant a project and environments The teammate can pull those environments, and gets PERMISSION_DENIED for the rest 9
Put the values in the project's environments pull writes them into .env 3, 4
Commit project-config.json to the repository No init after cloning 2

Handing someone a .env becomes granting them an environment. When someone leaves, removing them from the org stops their pulls, with no hunting for copies of a .env you sent them. Values they already read stay on their machine, so replace those (parts 9 and 11).

5. The whole series on one page

Steps 1 to 10 are what an admin sets up once. Step 11 is what each new teammate does once.

Step What you do Screen or command Part
1 Create an account, install the CLI, log in Create an account, npm i -g, dotvault login This part, 2
2 Put every environment's values in one project Projects, Common 3
3 Write keys and roll back a mistake dotvault set, versions, rollback 4
4 Ship .npmrc or kubeconfig as whole files, and stop secrets before a commit dotvault push, scan 5
5 Keep values used by several projects in one place Global Keys, bind 6
6 Hand CI a token and pull Service Tokens, DOTVAULT_TOKEN 7
7 Hand an AI agent a single token Service Tokens 8
8 Invite people, scope what they see, remove a leaver Company, + Invite member, Teams 9
9 Trace who did what Audit Log 10
10 Rotate a leaked key without an outage dotvault rotate 11
11 A new teammate gets the values dotvault login, init, pull This part, 2

6. What the free plan includes

The FAQ on dotvault.io answers "Is it free?" with "Yes. dotvault is published as a free tool for developers." The numbers for your org are on its Usage page, https://app.dotvault.io/admin/orgs/<org ID>/usage; dotvault whoami prints each org ID next to the org name.

The Usage page of the Company org Acme Shop, marked free. Resource counters: USERS 2 / 10, TEAMS 1 / 1, PROJECTS 3 / 25, KEYS (TOTAL) 2 / unlimited. Daily usage: SYNCS TODAY 0 / 1000, with the note "When the daily sync cap is reached, pulls for this organization are refused (429) until UTC midnight."

  • Company free plan, for a team. 10 users, one team, 25 projects, unlimited keys and 1,000 pulls a day (dotvault run counts too). Past 1,000, pulls for that org get a 429 until midnight UTC.
  • Personal, just for you. Unlimited projects and keys. The Usage page also shows PROJECTS and KEYS (TOTAL) as unlimited.

Both allow 10 environments per project and keep 14 days of audit history.

The Upgrade plan button on that page cannot be pressed; hovering over it shows "Contact a Platform Admin to upgrade your plan".

7. Where to ask

dotvault is run by EarthLink Network, linked as "Company" on dotvault.io. Questions can be sent through the dotvault contact page at https://www.dotvault.io/en/contact.

Wrapping up

An invited teammate gets the .env on an empty machine with four commands: install, login, init and pull. In the demo it took under 20 seconds. What makes that possible is the setup an admin does once, which is parts 1 to 10 of this series. Anyone can create a dotvault account and use it for free, so start with your own Personal org.

Terms

  • Personal / Company: the two kinds of dotvault org. A Personal org is just for you and exists from your first sign-in after signing up. A Company org is one you invite people into.
  • init: writes project-config.json in a project folder, linking that folder to a dotvault project.
  • Exit code: the number a command returns when it ends. 0 means success; dotvault returns a different number for each kind of failure. echo $? prints it.

dotvault stores the secrets in your .env and config files server-side and hands them to any authorised developer, CI job or AI agent with a single command (https://dotvault.io). Anyone can create an account and use it for free, and the steps in these articles are the steps you will use on day one.

If you find this useful, please like and follow.

Our products are listed at https://www.eln.ne.jp/products


EarthLink Network builds its own products to run the whole company on AI — each one born from a need along the way. See the full index of what we build:

→ The 18 products EarthLink Network builds in-house

For more about the company and each product, visit www.eln.ne.jp.

Top comments (0)