Skip to content

Commit efe96a7

Browse files
AcckiyGermanAcckiyGerman
authored
[docs] A lot of usage examples added into Readme. (#334)
* [docs] A lot of usage examples added into Readme.
1 parent 6fb0ad0 commit efe96a7

File tree

1 file changed

+168
-12
lines changed

1 file changed

+168
-12
lines changed

‎README.md‎

Lines changed: 168 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -19,24 +19,180 @@ With `data-cli` you can also:
1919
* Validate your data to ensure its quality
2020
* init a new dataset
2121
22-
## List of the `data-cli` commands
22+
## Usage examples:
2323
24-
Full description for each command ([help pages](https://github.com/datahq/data-cli/tree/master/docs)):
25-
- [data push](https://github.com/datahq/data-cli/blob/master/docs/push.md)
26-
- [data get](https://github.com/datahq/data-cli/blob/master/docs/get.md)
27-
- [data info](https://github.com/datahq/data-cli/blob/master/docs/info.md)
28-
- [data cat](https://github.com/datahq/data-cli/blob/master/docs/cat.md)
29-
- [data init](https://github.com/datahq/data-cli/blob/master/docs/init.md)
30-
- [data validate](https://github.com/datahq/data-cli/blob/master/docs/validate.md)
24+
Here we show examples of usage for common `data` commands. To see the full command documentation - click on the command name, or proceed to the [help pages](https://github.com/datahq/data-cli/tree/master/docs).
3125
26+
### data login
27+
28+
You should login at the first use of data-cli:
29+
```bash
30+
$ data login
31+
? Login with... Github
32+
> Opening browser and waiting for you to authenticate online
33+
> You are logged in!
34+
```
35+
36+
### [data push](https://github.com/datahq/data-cli/blob/master/docs/push.md)
37+
38+
Upload a dataset or a separate file on the DataHub:
39+
```bash
40+
$ data push mydata.csv
41+
? Please, confirm name for this dataset:
42+
0-selfish-cougar-7 mydataset
43+
? Please, confirm title for this dataset:
44+
Mydataset Mydataset
45+
Uploading [******************************] 100% (0.0s left)
46+
your data is published!
47+
🔗 https://datahub.io/myname/mydataset/v/1 (copied to clipboard)
48+
```
49+
**Note:** by default, findability flag for your dataset is set to `--unlisted`, meaning nobody else is able to see it, except you. Use `--public` flag to make it publicly available
50+
51+
### [data get](https://github.com/datahq/data-cli/blob/master/docs/get.md)
52+
53+
Get a dataset from the DataHub or GitHub:
54+
```bash
55+
$ data get http://datahub.io/core/gold-prices
56+
Time elapsed: 1.72 s
57+
Dataset/file is saved in "core/gold-prices"
58+
```
59+
60+
### [data info](https://github.com/datahq/data-cli/blob/master/docs/info.md)
61+
62+
Shows info about the dataset (local or remote):
63+
```bash
64+
$ data info http://datahub.io/core/gold-prices
65+
# Gold Prices (Monthly in USD)
66+
67+
Monthly gold prices since 1950 in USD (London market). Data is sourced from the Bundesbank.
68+
69+
## Data
70+
* [Bundesbank statistic ... [see more below]
71+
72+
## RESOURCES
73+
┌───────────────────┬────────┬───────┬───────┐
74+
│ Name │ Format │ Size │ Title │
75+
├───────────────────┼────────┼───────┼───────┤
76+
│ data_csv │ csv │ 16172 │ │
77+
├───────────────────┼────────┼───────┼───────┤
78+
│ data_json │ json │ 32956 │ │
79+
├───────────────────┼────────┼───────┼───────┤
80+
│ gold-prices_zip │ zip │ 17755 │ │
81+
├───────────────────┼────────┼───────┼───────┤
82+
│ data │ csv │ 16170 │ │
83+
└───────────────────┴────────┴───────┴───────┘
84+
85+
## README
86+
Monthly gold prices since 1950 in USD (London market). Data is sourced from the Bundesbank.
87+
...
88+
89+
### Licence
90+
...
91+
```
92+
93+
### [data cat](https://github.com/datahq/data-cli/blob/master/docs/cat.md)
94+
95+
Works similar as Unix `cat` command but works with remote resources and can convert tabular data into different formats:
96+
```bash
97+
$ data cat http://datahub.io/core/gold-prices/r/0.csv
98+
┌──────────────────────────────────────┬──────────────────────────────────────┐
99+
│ date │ price │
100+
├──────────────────────────────────────┼──────────────────────────────────────┤
101+
│ 1950-02-01 │ 34.730 │
102+
├──────────────────────────────────────┼──────────────────────────────────────┤
103+
│ 1950-03-01 │ 34.730 │
104+
105+
...........
106+
```
107+
You can also convert tabular data into different formats (the source could be remote as well):
108+
```bash
109+
$ data cat prices.csv prices.md
110+
> All done! Your data is saved in "prices.md"
111+
user@pc:~/Downloads$ cat prices.md
112+
| date | price |
113+
| ---------- | -------- |
114+
| 1950-02-01 | 34.730 |
115+
| 1950-03-01 | 34.730 |
116+
```
117+
118+
### [data init](https://github.com/datahq/data-cli/blob/master/docs/init.md)
119+
120+
Data-cli has an `init` command that will automatically generate Data Package metadata including scanning the current directory for data files and inferring [table schema] for tabular files:
121+
```bash
122+
$ data init
123+
This process initializes a new datapackage.json file.
124+
Once there is a datapackage.json file, you can still run `data init`
125+
to update/extend it.
126+
Press ^C at any time to quit.
127+
128+
? Enter Data Package name prices
129+
? Enter Data Package title prices
130+
? Do you want to add following file as a resource "prices.csv" - y/n? y
131+
prices.csv is just added to resources
132+
? Do you want to add following file as a resource "prices.xls" - y/n? y
133+
prices.xls is just added to resources
134+
135+
? Going to write to /home/user/Downloads/datapackage.json:
136+
{
137+
"name": "prices",
138+
"title": "prices",
139+
"resources": [
140+
{
141+
"path": "prices.csv",
142+
"name": "prices",
143+
"format": "csv",
144+
....
145+
},
146+
"schema": {
147+
"fields": [
148+
{
149+
"name": "date",
150+
"type": "date",
151+
"format": "default"
152+
},
153+
{
154+
........
155+
{
156+
"path": "prices.xls",
157+
"pathType": "local",
158+
"name": "prices",
159+
"format": "xls",
160+
"mediatype": "application/vnd.ms-excel",
161+
"encoding": "windows-1250"
162+
}
163+
]
164+
}
165+
166+
167+
Is that OK - y/n? y
168+
datapackage.json file is saved in /home/user/Downloads/datapackage.json
169+
```
170+
171+
### [data validate](https://github.com/datahq/data-cli/blob/master/docs/validate.md)
172+
173+
```bash
174+
$ data validate path/to/correct/datapackage
175+
> Your Data Package is valid!
176+
```
177+
```bash
178+
$ data validate path/to/invalid-data
179+
> Error! Validation has failed for "missing-column"
180+
> Error! The column header names do not match the field names in the schema on line 2
181+
182+
```
183+
184+
### data help
32185
33186
Also you can run "help" command in your terminal to see command docs:
34187
```shell
35-
data help
36-
> 'General description'
37-
data help push
188+
$ data help
189+
'General description'
190+
$ data help push
38191
> 'push command description'
39-
# etc...
192+
193+
# data help get
194+
# data help init
195+
# etc ...
40196
```
41197
42198
## Installation

0 commit comments

Comments
 (0)