1---
2layout: "intro"
3page_title: "Your First Secret - Getting Started"
4sidebar_title: "Your First Secret"
5sidebar_current: "gettingstarted-first-secret"
6description: |-
7  With the Vault server running, let's read and write our first secret.
8---
9
10# Your First Secret
11
12Now that the dev server is up and running, let's get straight to it and
13read and write our first secret.
14
15One of the core features of Vault is the ability to read and write
16arbitrary secrets securely. On this page, we'll do this using the CLI,
17but there is also a complete
18[HTTP API](/api/index.html)
19that can be used to programmatically do anything with Vault.
20
21Secrets written to Vault are encrypted and then written to backend
22storage. For our dev server, backend storage is in-memory, but in production
23this would more likely be on disk or in [Consul](https://www.consul.io).
24Vault encrypts the value before it is ever handed to the storage driver.
25The backend storage mechanism _never_ sees the unencrypted value and doesn't
26have the means necessary to decrypt it without Vault.
27
28## Writing a Secret
29
30Let's start by writing a secret. This is done very simply with the
31`vault kv` command, as shown below:
32
33```text
34$ vault kv put secret/hello foo=world
35Success! Data written to: secret/hello
36```
37
38This writes the pair `foo=world` to the path `secret/hello`. We'll
39cover paths in more detail later, but for now it is important that the
40path is prefixed with `secret/`, otherwise this example won't work. The
41`secret/` prefix is where arbitrary secrets can be read and written.
42
43You can even write multiple pieces of data, if you want:
44
45```text
46$ vault kv put secret/hello foo=world excited=yes
47Success! Data written to: secret/hello
48```
49
50`vault kv put` is a very powerful command. In addition to writing data
51directly from the command-line, it can read values and key pairs from
52`STDIN` as well as files. For more information, see the
53[command documentation](/docs/commands/index.html).
54
55~> **Warning:** The documentation uses the `key=value` based entry
56throughout, but it is more secure to use files if possible. Sending
57data via the CLI is often logged in shell history. For real secrets,
58please use files. See the link above about reading in from `STDIN` for more information.
59
60## Getting a Secret
61
62As you might expect, secrets can be gotten with `vault get`:
63
64```text
65$ vault kv get secret/hello
66Key                 Value
67---                 -----
68refresh_interval    768h
69excited             yes
70foo                world
71```
72
73As you can see, the values we wrote are given back to us. Vault gets
74the data from storage and decrypts it.
75
76The output format is purposefully whitespace separated to make it easy
77to pipe into a tool like `awk`.
78
79This contains some extra information. Many secrets engines create leases for
80secrets that allow time-limited access to other systems, and in those cases
81`lease_id` would contain a lease identifier and `lease_duration` would contain
82the length of time for which the lease is valid, in seconds.
83
84Optional JSON output is very useful for scripts. For example below we use the
85`jq` tool to extract the value of the `excited` secret:
86
87```text
88$ vault kv get -format=json secret/hello | jq -r .data.data.excited
89yes
90```
91
92When supported, you can also get a field directly:
93
94```text
95$ vault kv get -field=excited secret/hello
96yes
97```
98
99## Deleting a Secret
100
101Now that we've learned how to read and write a secret, let's go ahead
102and delete it. We can do this with `vault delete`:
103
104```text
105$ vault kv delete secret/hello
106Success! Data deleted (if it existed) at: secret/hello
107```
108
109## Next
110
111In this section we learned how to use the powerful CRUD features of
112Vault to store arbitrary secrets. On its own this is already a useful
113but basic feature.
114
115Next, we'll learn the basics about [secrets engines](/intro/getting-started/secrets-engines.html).
116